DEV Community: Waqar Habib

Stop Polluting Your Dev Inbox: A Developer's Guide to Temp Email in 2026

Waqar Habib — Fri, 03 Apr 2026 10:41:43 +0000

If you have been a developer for more than six months, your personal inbox is already a disaster. Every staging environment you have tested, every SaaS trial you spun up, every API you signed up for, they all have your email address now.

I used to have a folder in Gmail labeled 'dev junk.' It had over 14,000 unread emails. I deleted the folder. The problem was still there.

The fix is simpler than you think: stop using your real email for development tasks. Use a temporary email service instead. Here is what I learned after making this a core part of my workflow.

Why Developers Specifically Need Temp Email?

There are a few scenarios unique to developers where temporary email is genuinely essential rather than just convenient:

• Testing onboarding flows: You need to sign up as a new user 50 times while building a registration feature. Your real email receives 50 welcome sequences.
• QA and staging environments: Verifying that confirmation emails fire correctly without filling your inbox with test noise.
• API trials: Most B2B SaaS tools require a business email before giving you an API key. A temporary address lets you evaluate the docs before committing anything.
• Webhook testing: Setting up a throwaway inbox to catch and inspect webhook payloads in real time.
• Avoiding tracker pixels: Marketing tools embed invisible tracking pixels in emails. When you are in dev mode, you do not want your activity feeding into someone's analytics dashboard.
The Practical Setup

The fastest approach: keep a temporary email tab open whenever you are working in a development or testing context. Services like Temp Postal give you a fully functional inbox in under 10 seconds with no signup required, extended message storage, and a clean interface built for quickly copying verification codes.

You can generate a fresh inbox at any time at https://temppostal.com. No registration, no personal data required.

For teams, there is also real value in using temporary addresses for shared QA accounts. Nobody has to give up their personal email to be the designated test user for a sprint.

A Workflow That Actually Works
Here is the pattern that stuck for me after trying a few different approaches:
• Before starting any new feature that touches user registration or email-sending logic, open a fresh temporary inbox in a new browser tab.
• Use that address for all test signups during the sprint.
• At the end of the sprint, the inbox expires naturally. Zero cleanup required.
• For production smoke tests after a deploy, always use a fresh temporary address so you are testing with completely clean state.
The Security Consideration

Not all temporary email services handle data the same way. If you are testing flows that transmit sensitive information such as password reset tokens or account confirmation links, use a service that encrypts stored messages and does not expose inboxes publicly by default.

Temp Postal uses encrypted message storage and does not index inboxes publicly. For security-adjacent testing this distinction genuinely matters.

Wrapping Up
Your inbox is a resource. Stop leaking it to every service you interact with during development. A temporary email service is one of those small workflow improvements that compounds quietly over time: fewer distractions, cleaner test state, faster debugging cycles.
If you have a different approach to managing dev email chaos, drop it in the comments below.

SaaS Pricing Models and How They Affect Your Database Schema

Waqar Habib — Thu, 19 Mar 2026 06:54:48 +0000

Most SaaS architecture articles treat pricing as a product decision that lives in Stripe. The database schema is an afterthought. But your pricing model directly shapes your data model, and choosing the wrong schema for your pricing model creates expensive migration work when you need to change either one.

Here's how the four main SaaS pricing models translate to database architecture decisions.

Model 1: Flat Rate (One Price, Everyone Gets Everything)

Simple product, simple schema. Every user gets the same features for the same price.

CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  stripe_subscription_id VARCHAR(100),
  status VARCHAR(20),  -- 'active', 'cancelled', 'past_due'
  current_period_end TIMESTAMP,
  cancelled_at TIMESTAMP
);

This is the simplest model and works well for early-stage SaaS. The limitation: you can't charge different customers different amounts or offer different feature sets.

Model 2: Tiered Pricing (Starter / Growth / Enterprise)

Most SaaS companies end up here. Different plans with different feature sets and price points.

CREATE TABLE plans (
  id UUID PRIMARY KEY,
  name VARCHAR(50),         -- 'starter', 'growth', 'enterprise'
  stripe_price_id VARCHAR(100),
  monthly_price_cents INT,
  features JSONB,           -- feature flags per plan
  limits JSONB              -- usage limits per plan
);

-- Example features/limits JSON:
-- { "api_access": true, "webhooks": true, "sso": false }
-- { "max_users": 10, "max_projects": 50, "api_calls_monthly": 100000 }

CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  plan_id UUID REFERENCES plans(id),
  stripe_subscription_id VARCHAR(100),
  status VARCHAR(20),
  current_period_start TIMESTAMP,
  current_period_end TIMESTAMP
);

The features and limits JSONB columns let you change plan configurations without schema migrations. Adding a new feature flag is a data change, not a schema change.

Model 3: Usage-Based Pricing (Pay for What You Use)

Usage-based pricing (Twilio, AWS, OpenAI all use this model) requires a metering infrastructure that most schema designs don't account for.

-- Raw usage events: append-only, never update
CREATE TABLE usage_events (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  metric VARCHAR(50),      -- 'api_calls', 'ai_tokens', 'storage_gb', 'emails_sent'
  quantity DECIMAL(12,4),
  recorded_at TIMESTAMP DEFAULT NOW(),
  idempotency_key VARCHAR(100) UNIQUE  -- prevent double-counting
) PARTITION BY RANGE (recorded_at);  -- partition by month for query performance

-- Aggregate materialized view for billing calculations
CREATE MATERIALIZED VIEW monthly_usage AS
SELECT
  tenant_id,
  metric,
  DATE_TRUNC('month', recorded_at) AS month,
  SUM(quantity) AS total
FROM usage_events
GROUP BY tenant_id, metric, DATE_TRUNC('month', recorded_at);

-- Refresh periodically (or on demand for billing)
REFRESH MATERIALIZED VIEW CONCURRENTLY monthly_usage;

The idempotency_key is critical, usage events come from application code that might retry, and double-counting usage is a billing error that will upset customers and require manual reconciliation.

Model 4: Per-Seat Pricing (Charge Per User)

SaaS products that charge per user (Slack, Notion, Linear) need seat management infrastructure:

CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  plan_id UUID REFERENCES plans(id),
  stripe_subscription_id VARCHAR(100),
  status VARCHAR(20),
  -- Seat tracking
  included_seats INT,       -- seats in current billing cycle
  overage_seats INT DEFAULT 0,
  max_seats INT             -- hard limit if applicable
);

-- Track seat changes for proration calculation
CREATE TABLE seat_change_log (
  id UUID PRIMARY KEY,
  subscription_id UUID REFERENCES subscriptions(id),
  change_type VARCHAR(20),  -- 'added', 'removed'
  quantity INT,
  changed_at TIMESTAMP DEFAULT NOW(),
  stripe_adjustment_id VARCHAR(100)  -- proration invoice item
);

When a user is added mid-billing-cycle, you prorate and charge immediately. When removed, you credit the remaining days. Stripe handles the math, but you need to record the events.

The Add-On and Feature Flag Layer

Almost every SaaS eventually sells add-ons: individual features available for purchase on top of a base plan. The schema needs to support this without becoming a nightmare:

-- Add-ons available in your product
CREATE TABLE add_ons (
  id UUID PRIMARY KEY,
  name VARCHAR(100),
  stripe_price_id VARCHAR(100),
  feature_key VARCHAR(50) UNIQUE  -- matches feature flag name
);

-- Tenants that have purchased add-ons
CREATE TABLE tenant_add_ons (
  id UUID PRIMARY KEY,
  tenant_id UUID REFERENCES tenants(id),
  add_on_id UUID REFERENCES add_ons(id),
  stripe_subscription_item_id VARCHAR(100),
  active_from TIMESTAMP,
  active_until TIMESTAMP,  -- null = active indefinitely
  UNIQUE(tenant_id, add_on_id)
);

Feature gate check that merges plan features and add-ons:

async function tenantHasFeature(tenantId: string, featureKey: string): Promise<boolean> {
  const result = await db.query(`
    SELECT 1 FROM (
      -- Check plan features
      SELECT 1
      FROM subscriptions s
      JOIN plans p ON s.plan_id = p.id
      WHERE s.tenant_id = $1
        AND s.status = 'active'
        AND (p.features->$2)::boolean = true

      UNION ALL

      -- Check purchased add-ons
      SELECT 1
      FROM tenant_add_ons ta
      JOIN add_ons a ON ta.add_on_id = a.id
      WHERE ta.tenant_id = $1
        AND a.feature_key = $2
        AND ta.active_from <= NOW()
        AND (ta.active_until IS NULL OR ta.active_until > NOW())
    ) AS has_feature
  `, [tenantId, featureKey]);

  return result.rowCount > 0;
}

The Schema Decision That Costs the Most to Change

The hardest migration in SaaS architecture: moving from single-column plan field to a full subscription and usage model. Companies that start with tenants.plan = 'pro' and add billing complexity on top pay for it in data migrations.

If there's any chance your pricing will evolve beyond a single tier, build the subscription model from the start. The overhead is a few extra tables. The alternative is a multi-week migration while your billing system is live.

Pricing architecture is one of the foundational decisions in SaaS development that most tutorials overlook. I design SaaS data models with pricing models in mind from the start, for US clients building products that need to scale their business model alongside their code. Learn more at waqarhabib.com/services/saas-development.

Originally published at waqarhabib.com

Building Scalable E-commerce Backends with Node.js

Waqar Habib — Thu, 19 Mar 2026 06:52:41 +0000

E-commerce backends have a specific performance profile that generic web application architecture doesn't account for: extreme read-to-write ratios on product data, inventory operations that must be atomic, and traffic spikes during sales events that can be 50x normal load.

Here's how to build a Node.js e-commerce backend that handles US-scale traffic without collapsing under pressure.

Product Catalog Architecture

Product data is read thousands of times more than it's written. The architecture must reflect this.

Write path (low volume, latency tolerant):
  Admin updates product → PostgreSQL (source of truth)
  → Cache invalidation event → Redis + CDN

Read path (high volume, latency sensitive):
  Customer browses → Redis cache → (miss) → PostgreSQL → repopulate cache
  CDN cached pages → (miss) → App server → Redis

// Product service with caching layer
const PRODUCT_CACHE_TTL = 3600; // 1 hour

async function getProduct(productId: string): Promise<Product> {
  // Check cache first
  const cached = await redis.get(`product:${productId}`);
  if (cached) return JSON.parse(cached);

  // Cache miss: hit database
  const product = await db.query(
    'SELECT * FROM products WHERE id = $1 AND active = true',
    [productId]
  );

  if (!product) throw new NotFoundError('Product not found');

  // Populate cache
  await redis.setex(`product:${productId}`, PRODUCT_CACHE_TTL, JSON.stringify(product));
  return product;
}

// On product update: invalidate immediately
async function updateProduct(productId: string, updates: Partial<Product>) {
  await db.query('UPDATE products SET ... WHERE id = $1', [...]);
  await redis.del(`product:${productId}`); // Invalidate cache
  await redis.del(`category:${product.categoryId}`); // Invalidate category listing
}

Inventory Management, The Hard Part

Inventory is where e-commerce backends most commonly fail under load. Two customers can't buy the last item simultaneously, but at scale, preventing this without killing performance requires careful architecture.

The naive approach (don't use this):

-- This race condition will oversell your inventory
SELECT stock FROM products WHERE id = 1; -- returns 1
-- Meanwhile, another request also sees stock = 1
UPDATE products SET stock = stock - 1 WHERE id = 1;
-- Both decrement, stock goes to -1

The correct approach, optimistic locking with atomic operations:

-- Single atomic statement: only succeeds if stock > 0
UPDATE products
SET stock = stock - 1
WHERE id = $1 AND stock > 0
RETURNING id, stock;

-- If this returns 0 rows, stock is exhausted, no overselling

async function reserveInventory(
  productId: string,
  quantity: number,
  orderId: string
): Promise<boolean> {
  const result = await db.query(`
    UPDATE products
    SET stock = stock - $2,
        reserved = reserved + $2
    WHERE id = $1
      AND (stock - $2) >= 0  -- Prevent negative stock
    RETURNING id, stock
  `, [productId, quantity]);

  if (result.rowCount === 0) {
    return false; // Insufficient stock
  }

  // Record the reservation for rollback if order fails
  await db.query(
    'INSERT INTO inventory_reservations (product_id, quantity, order_id) VALUES ($1, $2, $3)',
    [productId, quantity, orderId]
  );

  return true;
}

Order Processing as a State Machine

Orders have complex lifecycles and things go wrong at every stage, payment fails, fulfillment rejects, shipping loses the package. Model orders as explicit state machines:

const ORDER_STATES = {
  PENDING:    'pending',
  CONFIRMED:  'confirmed',
  PROCESSING: 'processing',
  SHIPPED:    'shipped',
  DELIVERED:  'delivered',
  CANCELLED:  'cancelled',
  REFUNDED:   'refunded',
} as const;

const VALID_TRANSITIONS: Record<string, string[]> = {
  [ORDER_STATES.PENDING]:    [ORDER_STATES.CONFIRMED, ORDER_STATES.CANCELLED],
  [ORDER_STATES.CONFIRMED]:  [ORDER_STATES.PROCESSING, ORDER_STATES.CANCELLED],
  [ORDER_STATES.PROCESSING]: [ORDER_STATES.SHIPPED, ORDER_STATES.CANCELLED],
  [ORDER_STATES.SHIPPED]:    [ORDER_STATES.DELIVERED],
  [ORDER_STATES.DELIVERED]:  [ORDER_STATES.REFUNDED],
  [ORDER_STATES.CANCELLED]:  [],
  [ORDER_STATES.REFUNDED]:   [],
};

async function transitionOrder(orderId: string, newState: string) {
  const order = await getOrder(orderId);
  const allowed = VALID_TRANSITIONS[order.status] || [];

  if (!allowed.includes(newState)) {
    throw new Error(`Invalid transition: ${order.status} → ${newState}`);
  }

  await db.query(
    'UPDATE orders SET status = $1, updated_at = NOW() WHERE id = $2',
    [newState, orderId]
  );

  // Emit event for downstream processing
  await eventBus.emit(`order.${newState}`, { orderId, previousState: order.status });
}

Search That Doesn't Kill Your Database

Product search with PostgreSQL full-text search works up to ~100,000 products. Beyond that, you need Elasticsearch or OpenSearch.

// PostgreSQL full-text search (suitable for smaller catalogs)
async function searchProducts(query: string, filters: ProductFilters) {
  return db.query(`
    SELECT
      p.*,
      ts_rank(search_vector, plainto_tsquery('english', $1)) AS rank
    FROM products p
    WHERE
      search_vector @@ plainto_tsquery('english', $1)
      AND ($2::text IS NULL OR p.category = $2)
      AND ($3::numeric IS NULL OR p.price >= $3)
      AND ($4::numeric IS NULL OR p.price <= $4)
      AND p.active = true
    ORDER BY rank DESC
    LIMIT 50
  `, [query, filters.category, filters.minPrice, filters.maxPrice]);
}

For the search vector column, maintain it automatically with a trigger:

ALTER TABLE products ADD COLUMN search_vector tsvector;

CREATE INDEX products_search_idx ON products USING GIN(search_vector);

CREATE TRIGGER products_search_update
  BEFORE INSERT OR UPDATE ON products
  FOR EACH ROW EXECUTE FUNCTION
  tsvector_update_trigger(search_vector, 'pg_catalog.english', 'name', 'description', 'brand');

Flash Sale Traffic Handling

US e-commerce events (Black Friday, Cyber Monday, product launches) can spike traffic 50–100x in seconds. The architecture changes needed:

Pre-warm your auto-scaling groups 30 minutes before a scheduled sale
Move to a queue-based order system during peak: accept orders instantly, process them asynchronously
Implement a virtual waiting room for extreme events using a token bucket pattern
Cache your product pages aggressively at CloudFront, dynamic pages become a liability when your database is at capacity
Read replicas take all read traffic during sales events; primary handles writes only

E-commerce backend architecture is a balance of correctness (inventory never oversells, orders never lose state) and performance (product pages load fast, checkout doesn't time out). Getting both right requires intentional design, not accumulated patches.

I build e-commerce platforms and custom backends for US businesses that need more than Shopify can provide. See my work at waqarhabib.com/industries/ecommerce-platforms.

Originally published at waqarhabib.com

API-First Development, Why It Matters and How to Do It Right

Waqar Habib — Thu, 19 Mar 2026 06:34:00 +0000

API-first development is one of those phrases that gets thrown around a lot, usually by developer tool vendors and platform companies, without a clear explanation of what it actually means in practice.

Here's a concrete definition and a practical implementation guide, based on building APIs for US SaaS companies where the API is both an internal integration layer and a customer-facing product.

What API-First Actually Means

API-first means the API is designed before the implementation. Before you write a single line of Node.js, before you build a React component, you define the API contract: endpoints, request shapes, response shapes, error cases, authentication.

The contract is the primary artifact. The implementation fulfills it.

The alternative, what most teams actually do, is implementation-first: build the backend, see what it returns, build the frontend to consume it. The API becomes an afterthought and reflects internal implementation details that users have to work around.

OpenAPI as Your Contract Language

Write your API contract in OpenAPI (formerly Swagger). It's the standard, it has tooling support, and it generates documentation automatically:

# openapi.yaml
openapi: 3.1.0
info:
  title: YourApp API
  version: 1.0.0

paths:
  /projects:
    post:
      operationId: createProject
      summary: Create a new project
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized

components:
  schemas:
    CreateProjectRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: "Q4 Marketing Campaign"
        description:
          type: string
          maxLength: 500

    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

Generate Types from the Contract

With openapi-typescript, your OpenAPI spec generates TypeScript types automatically:

npx openapi-typescript openapi.yaml -o src/types/api.generated.ts

// src/types/api.generated.ts (generated, never edit manually)
export interface components {
  schemas: {
    CreateProjectRequest: {
      name: string;
      description?: string;
    };
    Project: {
      id: string;
      name: string;
      description: string | null;
      createdAt: string;
      updatedAt: string;
    };
  };
}

Now your frontend and backend both consume types generated from the same contract. A change to the OpenAPI spec propagates to both sides at compile time, mismatches become type errors, not runtime bugs.

Mock Server During Frontend Development

With the API contract defined, frontend development can start in parallel with backend development. @stoplight/prism generates a mock server from your OpenAPI spec:

npx @stoplight/prism-cli mock openapi.yaml --port 4010

The mock server returns realistic example responses based on your schema. Frontend developers build against the real API shape before the real backend exists, and when the real backend ships, switching from mock to real is a one-line environment variable change.

Contract Testing

Once both sides are built, contract tests verify that the implementation actually matches the contract:

// contract.test.ts
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import spec from '../openapi.json';

const ajv = new Ajv({ strict: false });
addFormats(ajv);

describe('POST /projects contract', () => {
  it('matches 201 response schema', async () => {
    const response = await request(app)
      .post('/projects')
      .set('Authorization', `Bearer ${testToken}`)
      .send({ name: 'Test Project' });

    expect(response.status).toBe(201);

    const validate = ajv.compile(spec.components.schemas.Project);
    expect(validate(response.body.data)).toBe(true);
    expect(validate.errors).toBeNull();
  });
});

This ensures your implementation can never silently diverge from your published contract.

Versioning Strategy for Customer-Facing APIs

When your API is a customer-facing product (not just an internal layer), breaking changes can break customer integrations. Deprecation policy before you have customers is much easier than after:

// Deprecation header: warns consumers before removal
app.use('/api/v1', (req, res, next) => {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', 'Sat, 31 Dec 2025 23:59:59 GMT');
  res.setHeader('Link', '</api/v2>; rel="successor-version"');
  next();
}, v1Router);

Give customers a minimum of 6 months notice before removing a versioned API. Enterprise US customers often have procurement and development cycles that make shorter windows impractical.

The Practical Benefits You'll Feel

Teams that adopt API-first consistently report:

Frontend and backend development parallelizes, no more waiting for backend to ship before frontend can start
Third-party integrations are easier because the contract is explicit
Onboarding new developers is faster, the OpenAPI spec is better documentation than any wiki
Bugs at API boundaries drop significantly because contract tests catch mismatches before production

If you're building a SaaS product where the API is a core deliverable, either as a developer product or as integration infrastructure, API design is worth getting right from day one. I specialize in API architecture and development for US SaaS companies at waqarhabib.com/services/api-development.

Originally published at waqarhabib.com

AI Feature Integration in SaaS, Practical Patterns for 2025

Waqar Habib — Thu, 19 Mar 2026 06:31:54 +0000

Every SaaS founder I talk to right now is asking some version of: "How do we add AI to our product?" The question is right but often framed wrong. The question isn't how to add AI, it's which specific user problems in your product have AI as the right solution, and how to integrate it without breaking what already works.

Here are the patterns I use when integrating AI into production SaaS products for US clients.

Pattern 1: LLM as a Feature, Not the Foundation

The most common mistake I see: building an entirely LLM-dependent product where every core workflow goes through an AI call. The problems compound:

LLM API latency (1–10 seconds) is incompatible with synchronous UI flows
LLM costs at scale are unpredictable and can make unit economics collapse
LLM outputs are non-deterministic, the same input can produce different outputs, making testing and QA much harder

The better pattern is AI as an enhancement layer on top of deterministic core functionality:

Your SaaS product core → deterministic, fast, testable
                ↓ (optional AI layer)
AI enhancement  → summarization, suggestions, classification
                ↓
User gets core value with or without AI; AI makes it better

If your product only works when the LLM call succeeds, you've built fragility into your core value proposition.

Pattern 2: Async AI Processing with Job Queues

Don't call LLM APIs synchronously in request handlers. The latency will kill your UI responsiveness.

// Bad: synchronous LLM call in request handler
app.post('/documents/:id/summarize', async (req, res) => {
  const document = await getDocument(req.params.id);
  const summary = await openai.chat.completions.create({...}); // 3-8 seconds
  await saveS ummary(document.id, summary);
  res.json({ summary }); // User waits 3-8 seconds staring at a spinner
});

// Good: queue job, return immediately, update UI via polling or WebSocket
app.post('/documents/:id/summarize', async (req, res) => {
  const job = await aiQueue.add('summarize-document', {
    documentId: req.params.id,
    userId: req.user.id,
  });
  res.json({ jobId: job.id, status: 'processing' }); // Returns in <100ms
});

// Worker process handles the actual LLM call
aiQueue.process('summarize-document', async (job) => {
  const document = await getDocument(job.data.documentId);
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'Summarize the following document concisely.' },
      { role: 'user', content: document.content },
    ],
  });
  const summary = response.choices[0].message.content;
  await saveS ummary(document.id, summary);
  await notifyUser(job.data.userId, 'summarize-complete', { documentId: document.id });
});

The frontend polls /jobs/:jobId/status or receives a WebSocket event when the summary is ready.

Pattern 3: Prompt Engineering as Code

Prompts are code. They should be versioned, tested, and reviewed like code. Don't embed prompts as inline strings scattered through your codebase:

// prompts/summarization.ts
export const DOCUMENT_SUMMARY_PROMPT = {
  version: 'v2.1',
  system: `You are a precise document summarizer for a US business context.
Produce summaries that are:
- 3-5 sentences maximum
- Written in active voice
- Focused on actionable information and key decisions
- Free of filler phrases like "The document discusses..." or "This text covers..."`,

  user: (document: string) => `Summarize this document:\n\n${document}`,
};

// Usage
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: DOCUMENT_SUMMARY_PROMPT.system },
    { role: 'user', content: DOCUMENT_SUMMARY_PROMPT.user(document.content) },
  ],
});

Version your prompts. When a prompt change improves quality, it should go through code review. When a prompt regression slips through, you can identify exactly which version introduced it.

Pattern 4: Output Validation

LLM outputs are untrustworthy for structured data. Always validate:

import { z } from 'zod';

const ClassificationSchema = z.object({
  category: z.enum(['bug', 'feature', 'question', 'billing', 'other']),
  priority: z.enum(['low', 'medium', 'high', 'urgent']),
  confidence: z.number().min(0).max(1),
  reasoning: z.string(),
});

async function classifyTicket(ticketText: string) {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [...],
    response_format: { type: 'json_object' }, // Force JSON output
  });

  const raw = JSON.parse(response.choices[0].message.content!);
  const result = ClassificationSchema.safeParse(raw);

  if (!result.success) {
    // LLM returned malformed output, fall back to manual review queue
    await queueForManualClassification(ticketText);
    return { category: 'other', priority: 'medium', confidence: 0, reasoning: 'AI classification failed' };
  }

  return result.data;
}

Never pass raw LLM output directly to a database write or a downstream system without validation.

Pattern 5: Cost Control

LLM costs can surprise you at scale. Build cost controls from the start:

// Track LLM costs per tenant per month
async function trackLLMUsage(tenantId: string, model: string, tokens: number) {
  const costPerToken = MODEL_COSTS[model] || 0;
  const cost = tokens * costPerToken;

  await db.query(`
    INSERT INTO llm_usage (tenant_id, model, tokens, cost_usd, date)
    VALUES ($1, $2, $3, $4, CURRENT_DATE)
    ON CONFLICT (tenant_id, model, date)
    DO UPDATE SET tokens = llm_usage.tokens + $3, cost_usd = llm_usage.cost_usd + $4
  `, [tenantId, model, tokens, cost]);

  // Check monthly budget
  const monthlyUsage = await getMonthlyUsage(tenantId);
  if (monthlyUsage.cost_usd > PLAN_LIMITS[tenant.plan].monthly_ai_budget) {
    throw new Error('AI_BUDGET_EXCEEDED');
  }
}

Separate AI costs by tenant so you can charge for them, enforce plan limits, and identify which customers are unprofitable at their current plan tier.

Pattern 6: Retrieval-Augmented Generation (RAG) for Accuracy

For any AI feature that needs to answer questions about your product's data, customer documents, knowledge bases, CRM notes, pure LLM answers will hallucinate. Use RAG:

// Simplified RAG pattern
async function answerWithContext(question: string, tenantId: string): Promise<string> {
  // 1. Embed the question
  const questionEmbedding = await openai.embeddings.create({
    input: question,
    model: 'text-embedding-3-small',
  });

  // 2. Find relevant context from vector store
  const relevantChunks = await vectorDb.query({
    vector: questionEmbedding.data[0].embedding,
    filter: { tenantId },
    topK: 5,
  });

  // 3. Use retrieved context in the prompt, not the LLM's training data
  const context = relevantChunks.map(c => c.text).join('\n\n');

  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: `Answer based only on this context:\n\n${context}` },
      { role: 'user', content: question },
    ],
  });

  return response.choices[0].message.content!;
}

RAG grounds LLM answers in your actual data, dramatically reducing hallucinations for domain-specific questions.

AI integration done right enhances your SaaS product without introducing fragility. The patterns above are what I use when building AI-powered features for US clients in production environments.

If you're adding AI capabilities to a SaaS product and want it built properly, see my AI development work at waqarhabib.com/services/ai-development.

Originally published at waqarhabib.com

DevOps for Startups, Setting Up CI/CD Without a Full DevOps Team

Waqar Habib — Thu, 19 Mar 2026 06:29:16 +0000

Most early-stage US startups don't have a dedicated DevOps engineer. They have developers who also manage infrastructure, which means CI/CD setups that either don't exist, break regularly, or were copy-pasted from a tutorial and nobody fully understands.

Here's a production-grade CI/CD setup that a small team can actually own and maintain, without needing a DevOps specialist on staff.

The Stack

For a US startup with a Node.js/React application deployed to AWS, this setup covers 95% of what you need:

Source control:      GitHub
CI/CD:               GitHub Actions
Container registry:  Amazon ECR
Orchestration:       Amazon ECS (Fargate)
Infrastructure:      Terraform
Secrets:             AWS Secrets Manager

All of these have generous free tiers or are inexpensive at startup scale.

The GitHub Actions Pipeline

Three workflows cover the full lifecycle:

# .github/workflows/ci.yml, runs on every PR
name: CI

on:
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: app_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run type check
        run: npm run type-check

      - name: Run tests
        run: npm test
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/app_test

      - name: Build
        run: npm run build

# .github/workflows/deploy-staging.yml, deploys on merge to develop
name: Deploy to Staging

on:
  push:
    branches: [develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push Docker image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/app:$IMAGE_TAG .
          docker push $ECR_REGISTRY/app:$IMAGE_TAG

      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: .aws/task-definition-staging.json
          service: app-staging
          cluster: app-staging
          wait-for-service-stability: true

The production deploy workflow is identical but triggers on merge to main and requires a manual approval gate in GitHub Environments.

Dockerfile for Production

# Multi-stage build: keeps the final image lean
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app

# Run as non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./

EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1

CMD ["node", "dist/app.js"]

The multi-stage build keeps your final Docker image small (no dev dependencies, no source files). The health check lets ECS know when a container is ready, and when to restart it.

Database Migrations in CI/CD

Database migrations are the trickiest part of a CI/CD pipeline. The safest approach:

# In your deploy workflow, before the ECS task update:
- name: Run database migrations
  run: |
    # Run migrations as a one-off ECS task, not in the web container startup
    aws ecs run-task \
      --cluster app-${{ env.ENVIRONMENT }} \
      --task-definition app-migrate-${{ env.ENVIRONMENT }} \
      --overrides '{"containerOverrides":[{"name":"migrate","command":["npm","run","migrate"]}]}' \
      --launch-type FARGATE \
      --network-configuration "..."

Never run migrations automatically on container startup. If a migration fails, you want it to fail loudly in CI before ECS tries to boot any web containers.

Environment Secrets

All secrets live in AWS Secrets Manager, never in GitHub secrets or environment files:

// Load secrets from AWS Secrets Manager at app startup
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';

async function loadSecrets() {
  const client = new SecretsManagerClient({ region: 'us-east-1' });
  const response = await client.send(new GetSecretValueCommand({
    SecretId: `app/${process.env.ENVIRONMENT}/secrets`
  }));
  const secrets = JSON.parse(response.SecretString!);
  Object.assign(process.env, secrets);
}

// Call before app initializes
await loadSecrets();

The ECS task role grants permission to read these secrets, no credentials needed in the container itself.

Monitoring: The Minimum You Need

A startup CI/CD setup is incomplete without alerting:

// CloudWatch metric filter → alarm → SNS → Slack/PagerDuty
// Add to your Terraform:

resource "aws_cloudwatch_metric_alarm" "error_rate" {
  alarm_name  = "${var.app_name}-${var.env}-5xx-rate"
  metric_name = "HTTPCode_Target_5XX_Count"
  namespace   = "AWS/ApplicationELB"

  statistic           = "Sum"
  period              = 60
  evaluation_periods  = 3
  threshold           = 10
  comparison_operator = "GreaterThanThreshold"

  alarm_actions = [aws_sns_topic.alerts.arn]
}

Three alarms are the minimum viable monitoring setup: 5xx error rate, response time (P99), and ECS task failure count.

This setup takes about a day to configure from scratch. After that, every PR gets tested automatically, staging deploys on every merge to develop, and production deploys are one approved merge away.

If you need DevOps infrastructure set up properly for a US startup, without hiring a full DevOps team, that's work I do. See my DevOps services at waqarhabib.com/services/devops-services.

Originally published at waqarhabib.com

EdTech Platform Architecture, Lessons from Real Builds

Waqar Habib — Thu, 19 Mar 2026 06:26:19 +0000

EdTech has unique technical requirements that general-purpose web app architecture doesn't prepare you for. Real-time collaboration, video delivery at scale, progress tracking across complex learning paths, accessibility compliance under Section 508 and WCAG 2.1, the combination creates architectural challenges that only become apparent when you're building for real educational institutions.

Here's what actually matters when architecting an EdTech platform for the US market.

Concurrent Users During Scheduled Events

General SaaS products have relatively predictable traffic. EdTech platforms get slammed during scheduled events: the Monday morning class login spike, the Sunday night homework rush, the exam period where every student in a district hits the platform simultaneously.

Your architecture needs to handle 10x normal traffic for short, predictable bursts. The implications:

Horizontal scaling must be automatic and fast. ECS with Application Auto Scaling configured to scale based on CPU and request count, not memory alone. With containers, you can go from 5 to 50 instances in under 2 minutes if your scaling policies are aggressive enough.

# ECS Auto Scaling configuration
resource "aws_appautoscaling_policy" "ecs_scale_up" {
  policy_type        = "TargetTrackingScaling"

  target_tracking_scaling_policy_configuration {
    target_value = 60.0 # Scale when CPU hits 60%

    customized_metric_specification {
      metric_name = "RequestCountPerTarget"
      namespace   = "AWS/ApplicationELB"
      statistic   = "Sum"
    }

    scale_in_cooldown  = 300  # 5 min before scaling in (avoid flapping)
    scale_out_cooldown = 30   # 30 sec to scale out (be aggressive on the way up)
  }
}

Database read replicas for heavy read loads. During class time, 90% of database queries are reads, students loading content, checking progress, retrieving assignments. Route reads to read replicas and reserve the primary for writes.

Real-Time Collaboration Architecture

EdTech products increasingly need real-time features: live classroom tools, collaborative documents, shared whiteboards. The technology stack depends on the interaction pattern:

Low-frequency updates (quiz responses, progress saves):
  → HTTP polling every 5-10 seconds is fine

Medium-frequency updates (chat, activity feed):
  → WebSockets via Socket.io

High-frequency updates (live cursor collaboration, whiteboard drawing):
  → WebRTC for peer-to-peer, or WebSockets with a CRDT library

For WebSocket at scale, don't use a single Socket.io server, use Socket.io with Redis adapter so WebSocket connections can be distributed across multiple nodes:

import { Server } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();

await Promise.all([pubClient.connect(), subClient.connect()]);

const io = new Server(httpServer);
io.adapter(createAdapter(pubClient, subClient));

// Now events published on one server instance are received by clients
// connected to other instances, works across your entire ECS cluster

Video Delivery Architecture

Video is the backbone of most EdTech platforms and the most expensive thing to get wrong. Serving video files directly from S3 doesn't scale and destroys your AWS data transfer budget.

The correct architecture:

Content Upload:
  Instructor uploads → S3 raw storage → Lambda trigger → MediaConvert job
  → Transcoded to HLS (multiple bitrates) → CloudFront distribution

Content Delivery:
  Student requests video → CloudFront edge (cached near the student)
  → Signed URL with expiry (prevent sharing/leeching)
  → Adaptive bitrate streaming (HLS) → adjusts quality to connection speed

// Generate signed CloudFront URL for protected video content
import { getSignedUrl } from '@aws-sdk/cloudfront-signer';

async function getVideoUrl(videoKey: string, studentId: string): Promise<string> {
  // Log video access for completion tracking
  await trackVideoAccess(videoKey, studentId);

  return getSignedUrl({
    url: `https://${process.env.CLOUDFRONT_DOMAIN}/videos/${videoKey}/manifest.m3u8`,
    keyPairId: process.env.CLOUDFRONT_KEY_PAIR_ID,
    privateKey: process.env.CLOUDFRONT_PRIVATE_KEY,
    dateLessThan: new Date(Date.now() + 3600 * 1000).toISOString(), // 1 hour expiry
  });
}

Learning Progress Tracking

Progress tracking sounds simple until you're tracking completion across: individual lessons, modules, courses, learning paths, certifications, with prerequisites, prerequisites with minimum scores, and time-based unlocking.

The data model that handles this:

-- Enrollment tracks the student-course relationship
CREATE TABLE enrollments (
  id UUID PRIMARY KEY,
  student_id UUID REFERENCES users(id),
  course_id UUID REFERENCES courses(id),
  enrolled_at TIMESTAMP,
  completed_at TIMESTAMP,
  UNIQUE(student_id, course_id)
);

-- Progress tracks individual content item completion
CREATE TABLE progress (
  id UUID PRIMARY KEY,
  enrollment_id UUID REFERENCES enrollments(id),
  content_item_id UUID REFERENCES content_items(id),
  status VARCHAR(20) CHECK (status IN ('not_started', 'in_progress', 'completed')),
  score DECIMAL(5,2),       -- quiz score if applicable
  time_spent_seconds INT,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  UNIQUE(enrollment_id, content_item_id)
);

-- Prerequisites: content_item B requires content_item A with min score
CREATE TABLE prerequisites (
  content_item_id UUID REFERENCES content_items(id),
  requires_item_id UUID REFERENCES content_items(id),
  minimum_score DECIMAL(5,2) DEFAULT NULL
);

FERPA Compliance for US Educational Data

If your EdTech platform handles data for US students under 18 in a school setting, FERPA applies. Key developer requirements:

Student educational records cannot be shared with third parties without parental consent (or the student's own consent if 18+)
Directory information (name, email) can be shared only if the institution has given proper notice
Every third-party service receiving student data needs a formal School Official exception or data processing agreement
Parents have the right to access and correct their child's educational records, build this capability in from the start

In practice: don't pipe student data to Google Analytics, Mixpanel, or Segment without a proper FERPA agreement with those vendors. Many edtech companies have learned this the hard way.

Accessibility Is Not Optional

US educational institutions are bound by Section 508 and often require WCAG 2.1 AA compliance in procurement contracts. If you're selling to US school districts, inaccessible software will fail procurement review.

Practical checklist for EdTech accessibility:

All video content has captions (auto-captions from AWS Transcribe, then human review)
All images have meaningful alt text
All interactive elements are keyboard navigable
Color contrast ratio meets WCAG AA (4.5:1 for normal text)
Screen reader testing with NVDA/JAWS before launch
Focus management in single-page app routing

EdTech architecture decisions made early, especially around video delivery, real-time features, and compliance, determine whether your platform can scale to serve real US institutions or stays a prototype.

I've built EdTech platforms for US educational markets, including compliance with FERPA and Section 508. Learn more at waqarhabib.com/industries/edtech-development.

Originally published at waqarhabib.com

How to Build a FinTech MVP Without Breaking Compliance Rules

Waqar Habib — Thu, 19 Mar 2026 06:06:34 +0000

FinTech is the most compliance-dense space in software development. PCI DSS for card payments, SOC 2 for enterprise sales, BSA/AML for money movement, GLBA for financial data, before you write your first line of code, the regulatory landscape for a US FinTech product can feel paralyzing.

But here's the thing: most early-stage US FinTech MVPs don't need to solve all of this at once. The key is knowing which compliance requirements apply to your specific product at your specific stage, and building your architecture so you can add the rest incrementally.

The First Question: Are You Handling Money Directly?

This single distinction determines most of your compliance burden:

Payments facilitation (direct): You're moving money, collecting payments, disbursing funds, holding balances. You need PCI DSS compliance and potentially a money transmitter license.

Payments facilitation (via partner): Stripe, Plaid, Braintree handle the actual money movement. You use their APIs. Your PCI scope is dramatically reduced, often to SAQ-A level, which is manageable.

For most FinTech MVPs, the right answer is: use compliant infrastructure providers and stay out of the direct money movement business until you have scale and resources for full licensing.

PCI DSS Scope Reduction

If you're accepting credit cards, PCI DSS applies. But the scope varies enormously depending on your implementation:

SAQ-A (simplest): 
  - You use an iframe or redirect for payment collection
  - Card data never touches your servers
  - Example: Stripe.js with the card element
  - 22 requirements to satisfy

SAQ-D (most complex):
  - You collect card data directly
  - You transmit and process card data on your infrastructure
  - 300+ requirements
  - Quarterly vulnerability scans required
  - Annual QSA assessment

The implementation difference:

// SAQ-D scope (don't do this unless you must):
app.post('/payment', async (req, res) => {
  const { cardNumber, cvv, expiry } = req.body; // card data on your server
  // You are now fully in-scope for PCI DSS SAQ-D
});

// SAQ-A scope (use this):
// Frontend: Stripe.js creates a token without card data hitting your server
const { paymentMethod } = await stripe.createPaymentMethod({
  type: 'card',
  card: cardElement, // Stripe's iframe element
});

// Backend: only receives a token, never card data
app.post('/payment', async (req, res) => {
  const { paymentMethodId, amount } = req.body; // no card data
  const paymentIntent = await stripe.paymentIntents.create({
    amount,
    currency: 'usd',
    payment_method: paymentMethodId,
  });
});

Data Architecture for Financial Applications

Financial data has specific storage requirements that differ from standard web apps:

Immutable audit trails: Financial records should never be updated or deleted, only appended. Use an event sourcing pattern:

// Instead of updating a balance record:
// BAD: UPDATE accounts SET balance = 1500 WHERE id = 'acc_123'

// Use an append-only ledger:
await db.query(`
  INSERT INTO ledger_entries
    (account_id, amount, type, reference_id, timestamp, balance_after)
  VALUES ($1, $2, $3, $4, NOW(), $5)
`, [accountId, amount, 'CREDIT', transferId, newBalance]);

The current balance is derived by summing ledger entries, never stored as a mutable field. This is how real financial systems work and it's what regulators expect.

Data retention: Financial records in the US must typically be retained for 5–7 years depending on the record type. Design your deletion/anonymization policies accordingly, you often cannot delete financial records even when a user closes their account.

API Security for FinTech

Beyond standard API security practices, FinTech APIs need additional controls:

// Idempotency keys: prevent duplicate transactions
app.post('/transfers', async (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'];
  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Idempotency-Key header required' });
  }

  // Check if we've seen this key before
  const existing = await redis.get(`idempotency:${idempotencyKey}`);
  if (existing) {
    return res.json(JSON.parse(existing)); // Return cached result
  }

  const result = await processTransfer(req.body);

  // Cache result for 24 hours
  await redis.setex(`idempotency:${idempotencyKey}`, 86400, JSON.stringify(result));
  res.json(result);
});

Idempotency keys are essential for any money-movement API, network failures and retries must never result in duplicate transactions.

Fraud Prevention Architecture

Basic fraud controls for a FinTech MVP:

// Velocity checks: flag unusual transaction patterns
async function checkTransactionVelocity(userId: string, amount: number): Promise<boolean> {
  const oneHourAgo = new Date(Date.now() - 3600000);

  const recentTotal = await db.query(`
    SELECT COALESCE(SUM(amount), 0) as total, COUNT(*) as count
    FROM transactions
    WHERE user_id = $1 AND created_at > $2 AND status = 'completed'
  `, [userId, oneHourAgo]);

  const { total, count } = recentTotal.rows[0];

  // Flag if: more than 10 transactions/hour OR more than $5,000/hour
  if (count > 10 || parseFloat(total) + amount > 5000) {
    await flagForReview(userId, 'VELOCITY_EXCEEDED');
    return false; // Block transaction pending review
  }
  return true;
}

More sophisticated fraud prevention (ML-based, behavioral analytics) comes later. For an MVP, velocity limits and rule-based checks catch the most common fraud patterns.

The Infrastructure Choices That Matter for Compliance

Cloud region: Keep US customer financial data in us-east-1 or us-west-2. Some enterprise and government clients contractually require this.
SOC 2 readiness: Use AWS services that are already SOC 2 certified (most managed services are). This doesn't make you SOC 2 certified, but it means your infrastructure layer is compliant.
Encryption: All financial data encrypted at rest and in transit. Use KMS for key management, never roll your own encryption.
VPC isolation: Database and internal services should never be publicly accessible.

Building a FinTech MVP in the US requires architectural decisions that look over-engineered on day one but save you from expensive rebuilds when you're handling real money for real users.

I've built FinTech applications for US clients navigating PCI, SOC 2, and enterprise compliance requirements. If you're building in this space, see my FinTech development work at waqarhabib.com/industries/fintech-development.

Originally published at waqarhabib.com

Building HIPAA-Compliant Web Apps, A Developer's Guide

Waqar Habib — Thu, 19 Mar 2026 06:03:48 +0000

HIPAA is one of those compliance frameworks that developers either treat as a vague legal requirement (dangerous) or an impenetrable bureaucratic maze (also dangerous). The reality is more practical: HIPAA has specific technical requirements, and if you're building a US healthcare web application that handles Protected Health Information (PHI), you need to implement them.

This guide covers the developer-facing requirements. It is not legal advice, if you're launching a healthcare product, get a HIPAA attorney. But this gives you the technical picture.

What Counts as PHI

Protected Health Information is individually identifiable health information tied to a person. That means any of the following, combined with health data:

Name, address, date of birth, phone number, email
Social Security Number, account numbers, certificate numbers
Any unique identifier that could identify the individual

The common developer mistake: assuming only medical records are PHI. A user's email address combined with the fact that they have an account on your mental health app is PHI. Their IP address in your logs, tied to a healthcare visit, is PHI.

The Technical Safeguards You Must Implement

HIPAA's Security Rule specifies four categories of technical safeguards:

1. Access Controls

// Role-Based Access Control, enforce at the API layer
const PERMISSIONS = {
  'patient': ['read:own_records', 'write:own_profile'],
  'provider': ['read:patient_records', 'write:clinical_notes'],
  'admin': ['read:all', 'write:all', 'delete:records'],
  'billing': ['read:insurance_info', 'write:billing_codes'],
} as const;

function authorize(requiredPermission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const userPermissions = PERMISSIONS[req.user.role] || [];
    if (!userPermissions.includes(requiredPermission)) {
      // Log access denial, HIPAA requires audit trails
      auditLog.warn({
        event: 'ACCESS_DENIED',
        userId: req.user.id,
        resource: req.path,
        requiredPermission,
      });
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

Minimum necessary access is a core HIPAA principle, users should only see the PHI they need for their specific role.

2. Audit Controls (This Is Where Most Apps Fall Short)

HIPAA requires you to track who accessed what PHI, when, and from where. Every read, write, and delete of PHI must be logged:

// Audit logging middleware for PHI access
async function auditPhiAccess(
  userId: string,
  action: 'READ' | 'CREATE' | 'UPDATE' | 'DELETE',
  resourceType: string,
  resourceId: string,
  req: Request
) {
  await db.query(`
    INSERT INTO phi_audit_log
      (user_id, action, resource_type, resource_id, ip_address, user_agent, timestamp)
    VALUES ($1, $2, $3, $4, $5, $6, NOW())
  `, [
    userId,
    action,
    resourceType,
    resourceId,
    req.ip,
    req.headers['user-agent'],
  ]);
}

// Usage in a service
async function getPatientRecord(patientId: string, requestingUser: User, req: Request) {
  const record = await db.query('SELECT * FROM patient_records WHERE id = $1', [patientId]);
  await auditPhiAccess(requestingUser.id, 'READ', 'patient_record', patientId, req);
  return record;
}

Audit logs must be retained for at least 6 years and must be tamper-evident. Store them separately from application logs.

3. Transmission Security

All PHI transmitted over any network must be encrypted. In practice:

- HTTPS everywhere, TLS 1.2 minimum (TLS 1.3 preferred)
- HSTS header enforced: Strict-Transport-Security: max-age=31536000; includeSubDomains
- No PHI in URL query parameters (they appear in logs and browser history)
- No PHI in JWT payloads unless the JWT is encrypted (JWE), not just signed (JWS)
- API responses must not include PHI fields not required by the request

4. Encryption at Rest

PHI stored in databases, file systems, or backups must be encrypted at rest:

AWS implementation:
- RDS: enable encryption at rest (uses AES-256 via KMS)
- S3: bucket-level SSE-S3 or SSE-KMS encryption
- EBS volumes: encrypted
- CloudWatch Logs containing PHI: encrypted with KMS key
- Backups: encrypted, verify this explicitly, it's not always default

Business Associate Agreements (BAAs)

Every third-party service that handles PHI on your behalf must sign a Business Associate Agreement. This is a legal document, but as a developer you need to know which services require one:

You MUST have a BAA with:

Your cloud provider (AWS, Azure, GCP, they all offer BAAs)
Your database hosting provider
Any logging service that receives PHI (Datadog, Splunk, etc.)
Email service providers if you send PHI via email (SendGrid, Mailgun)
Analytics platforms if they receive PHI

Common mistake: Using a third-party error tracking service (Sentry, Bugsnag) without a BAA, and having PHI appear in error reports. Scrub PHI from error objects before they reach external services:

// Sanitize before sending to Sentry
Sentry.configureScope(scope => {
  scope.addEventProcessor(event => {
    // Remove PHI fields from request data
    if (event.request?.data) {
      const { ssn, dob, medicalRecordNumber, ...safe } = event.request.data;
      event.request.data = safe;
    }
    return event;
  });
});

Password and Session Requirements

Passwords must meet complexity requirements (NIST 800-63B is the current US standard)
Automatic session timeout required, 15 minutes of inactivity is common in healthcare
MFA strongly recommended and often contractually required by covered entities

// Session timeout middleware
const SESSION_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes

app.use((req, res, next) => {
  if (req.session?.lastActivity) {
    const timeSinceActivity = Date.now() - req.session.lastActivity;
    if (timeSinceActivity > SESSION_TIMEOUT_MS) {
      req.session.destroy();
      return res.status(401).json({ error: 'SESSION_EXPIRED', message: 'Session timed out due to inactivity' });
    }
  }
  req.session.lastActivity = Date.now();
  next();
});

The Breach Notification Reality

HIPAA requires notifying affected individuals within 60 days of discovering a breach. If more than 500 individuals in a US state are affected, you also notify the Secretary of HHS and prominent media outlets in that state.

This means your incident response plan needs to include: breach detection, scope assessment, and notification workflows. Building this after a breach is too late.

HIPAA compliance is achievable with disciplined engineering. It's not magic, it's specific technical controls, consistently implemented and documented.

I've built HIPAA-compliant web applications for US healthcare clients and understand both the technical and compliance requirements. If you're building in this space, see my healthcare development work at waqarhabib.com/industries/healthcare-web-apps.

Originally published at waqarhabib.com

How to Structure a REST API for a SaaS Product (Node.js + Express)

Waqar Habib — Thu, 19 Mar 2026 05:58:00 +0000

A REST API for a SaaS product is not the same as a REST API for a simple CRUD app. The scale is different. The multi-tenancy is different. The versioning requirements are different. The error handling expectations from paying customers are different.

I've designed and built dozens of production APIs for US SaaS companies. Here's the structure I arrive at consistently, with explanations for why each decision exists.

Directory Structure First

How you organize your files determines how your team scales. Here's the structure I use for Node.js + Express SaaS APIs:

src/
├── api/
│   ├── v1/
│   │   ├── routes/
│   │   │   ├── users.routes.ts
│   │   │   ├── projects.routes.ts
│   │   │   └── billing.routes.ts
│   │   ├── controllers/
│   │   │   ├── users.controller.ts
│   │   │   └── projects.controller.ts
│   │   └── index.ts
│   └── v2/               # future version
├── services/
│   ├── user.service.ts
│   ├── project.service.ts
│   └── billing.service.ts
├── middleware/
│   ├── auth.middleware.ts
│   ├── tenant.middleware.ts
│   ├── rateLimit.middleware.ts
│   └── errorHandler.middleware.ts
├── models/
│   └── (Prisma schema or Knex models)
├── validators/
│   ├── user.validator.ts
│   └── project.validator.ts
├── utils/
│   ├── response.util.ts
│   └── pagination.util.ts
└── app.ts

The separation between routes, controllers, and services is intentional. Routes define the HTTP shape. Controllers handle request/response translation. Services contain business logic with no HTTP dependencies. This separation means you can test services without HTTP, and swap your HTTP framework without rewriting business logic.

Consistent Response Envelope

Every response from your API should have the same outer shape. This makes frontend integration predictable and lets you add metadata without breaking clients:

// utils/response.util.ts
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: Record<string, string[]>; // field-level validation errors
  };
  meta?: {
    page?: number;
    perPage?: number;
    total?: number;
    requestId?: string;
  };
}

export function successResponse<T>(data: T, meta?: ApiResponse<T>['meta']): ApiResponse<T> {
  return { success: true, data, meta };
}

export function errorResponse(
  code: string,
  message: string,
  details?: Record<string, string[]>
): ApiResponse<never> {
  return { success: false, error: { code, message, details } };
}

// In a controller
async function getUser(req: Request, res: Response) {
  const user = await userService.findById(req.params.id);
  res.json(successResponse(user));
}

Your frontend developers will thank you for this. No more guessing whether errors come in error.message, message, errors[0], or some other shape.

Request Validation Before Controllers Touch Data

Never let unvalidated data reach your service layer. Validate at the route level using Zod schemas:

// validators/project.validator.ts
import { z } from 'zod';

export const CreateProjectSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  visibility: z.enum(['public', 'private']).default('private'),
});

export const UpdateProjectSchema = CreateProjectSchema.partial();

export type CreateProjectDTO = z.infer<typeof CreateProjectSchema>;
export type UpdateProjectDTO = z.infer<typeof UpdateProjectSchema>;

// middleware: validation factory
export function validate(schema: z.ZodSchema) {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      const details = result.error.flatten().fieldErrors;
      return res.status(400).json(errorResponse('VALIDATION_ERROR', 'Invalid request body', details));
    }
    req.body = result.data; // Replace with parsed, type-safe data
    next();
  };
}

// routes/projects.routes.ts
router.post('/', authenticate, validate(CreateProjectSchema), projectController.create);
router.patch('/:id', authenticate, validate(UpdateProjectSchema), projectController.update);

Authentication Middleware with Tenant Scoping

In a multi-tenant SaaS, authentication and tenant resolution happen together:

// middleware/auth.middleware.ts
export async function authenticate(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return res.status(401).json(errorResponse('UNAUTHORIZED', 'No token provided'));
  }

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET) as JWTPayload;
    const user = await userService.findById(payload.userId);
    const tenant = await tenantService.findById(payload.tenantId);

    // Attach to request for downstream handlers
    req.user = user;
    req.tenant = tenant;
    next();
  } catch (err) {
    return res.status(401).json(errorResponse('INVALID_TOKEN', 'Token expired or invalid'));
  }
}

API Versioning From Day One

Most teams skip versioning until they need it. By then it's painful to add. Build it in from the start:

// app.ts
import v1Router from './api/v1';

app.use('/api/v1', v1Router);
// app.use('/api/v2', v2Router); // when ready

When you need to make a breaking change, changing a field name, removing an endpoint, changing authentication, you create /api/v2 and migrate clients gradually. Existing integrations on /api/v1 keep working.

Version in the URL, not in headers. Headers are technically more "RESTful" but URL versioning is more practical: it works with caching, it's visible in logs, and your API clients can hardcode it clearly.

Pagination That Doesn't Break at Scale

Offset pagination (LIMIT 100 OFFSET 1000) is simple but breaks at scale, PostgreSQL has to scan and discard 1000 rows to return your page. For large tables, use cursor-based pagination:

// utils/pagination.util.ts
interface CursorPaginationParams {
  cursor?: string;   // ID of last item on previous page
  limit: number;
}

interface CursorPaginationResult<T> {
  items: T[];
  nextCursor: string | null;
  hasMore: boolean;
}

export async function paginateWithCursor<T extends { id: string }>(
  query: (params: { cursor?: string; limit: number }) => Promise<T[]>,
  params: CursorPaginationParams
): Promise<CursorPaginationResult<T>> {
  const { cursor, limit } = params;
  const items = await query({ cursor, limit: limit + 1 }); // fetch one extra

  const hasMore = items.length > limit;
  const pageItems = hasMore ? items.slice(0, limit) : items;
  const nextCursor = hasMore ? pageItems[pageItems.length - 1].id : null;

  return { items: pageItems, nextCursor, hasMore };
}

-- Cursor-based query: much faster than OFFSET
SELECT * FROM projects
WHERE tenant_id = $1
  AND (id > $2 OR $2 IS NULL)
ORDER BY id ASC
LIMIT $3;

Global Error Handler

Never let unhandled errors leak stack traces to API clients. One global error handler catches everything:

// middleware/errorHandler.middleware.ts
export function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  _next: NextFunction
) {
  // Log full error internally
  logger.error({ err, url: req.url, method: req.method, tenantId: req.tenant?.id });

  // Known application errors
  if (err instanceof AppError) {
    return res.status(err.statusCode).json(errorResponse(err.code, err.message));
  }

  // Prisma / database errors
  if (err instanceof Prisma.PrismaClientKnownRequestError) {
    if (err.code === 'P2002') {
      return res.status(409).json(errorResponse('DUPLICATE_ENTRY', 'Resource already exists'));
    }
  }

  // Unknown errors: generic message to client, full details in logs
  return res.status(500).json(
    errorResponse('INTERNAL_ERROR', 'Something went wrong. Our team has been notified.')
  );
}

// Register last in app.ts
app.use(errorHandler);

US enterprise clients and compliance frameworks (SOC 2, HIPAA) expect that your API never leaks internal implementation details, stack traces, SQL queries, server paths, in error responses. This handler ensures that.

Rate Limiting Per Tenant

Global rate limiting is not enough for a SaaS product. One tenant hammering your API shouldn't affect others:

import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';

export function tenantRateLimit(windowMs: number, max: number) {
  return rateLimit({
    windowMs,
    max,
    keyGenerator: (req) => `tenant:${req.tenant?.id}:${req.ip}`,
    store: new RedisStore({ client: redisClient }),
    handler: (req, res) => {
      res.status(429).json(errorResponse(
        'RATE_LIMITED',
        `Too many requests. Limit is ${max} per ${windowMs / 1000}s.`
      ));
    }
  });
}

// Apply different limits to different route groups
router.use('/api/v1/webhooks', tenantRateLimit(60_000, 10));   // strict
router.use('/api/v1',          tenantRateLimit(60_000, 1000)); // standard

This structure has served well across dozens of production SaaS APIs serving US business customers. The key philosophy: make the right thing easy and the wrong thing hard. Validation middleware means you can't skip validation. A global error handler means you can't accidentally leak internals. A response envelope means you can't return an inconsistent shape.

If you're building a SaaS API and want it done right from the start, API architecture and development is one of the core services I offer at waqarhabib.com/services/api-development.

Originally published at waqarhabib.com

AWS Cloud Migration Checklist: Moving a Legacy App to the Cloud

Waqar Habib — Thu, 19 Mar 2026 05:49:29 +0000

Cloud migration projects fail for predictable reasons. Not because the technology is hard but because AWS is well-documented and the tooling is mature. They fail because teams skip the audit phase, underestimate data migration complexity, and try to lift-and-shift architectures that were never designed for the cloud.

I've led cloud migrations for US businesses across FinTech, healthcare, and SaaS from single-server monoliths to multi-region systems. This checklist captures what actually needs to happen before, during, and after migration.

Phase 1: Pre-Migration Audit (Do Not Skip This)

Before touching AWS, you need a complete picture of what you're moving.

Application inventory:

[ ] List every service, process, and scheduled job running on your current infrastructure
[ ] Map all external dependencies: third-party APIs, payment processors, email providers
[ ] Document every port, protocol, and network path between services
[ ] Identify stateful vs stateless components: They migrate differently

Data inventory:

[ ] Catalog every database: type, size, read/write patterns, peak load times
[ ] Identify data with compliance constraints (PII, PHI, PCI): This affects your AWS region choices and service selections
[ ] Measure your RTO (Recovery Time Objective) and RPO (Recovery Point Objective) requirements: These drive your backup and replication strategy
[ ] Document any data that cannot be in certain geographic regions (US-only requirements are common for government and healthcare clients)

Traffic baseline:

[ ] Capture 30 days of traffic patterns: requests/second, peak times, geographic distribution
[ ] Profile database query patterns: identify slow queries, N+1 problems, missing indexes
[ ] Measure current response times as your benchmark: You need to beat these after migration

Phase 2: Architecture Decisions

Choose your migration strategy:

Strategy	When to use	Risk
Lift and Shift (Rehost)	Time-constrained, prove cloud works first	Misses cloud-native optimisations
Replatform	Swap DB for RDS, storage for S3 with minimal code changes	Moderate
Refactor / Re-architect	When the current architecture is a long-term bottleneck	High effort, high reward

For most US SaaS companies I work with, replatform is the right starting point. You get the reliability and scaling benefits of managed services without a full rewrite.

Key AWS service decisions:

Compute:
  Stateless web servers → ECS (Fargate) or EC2 Auto Scaling Groups
  Scheduled jobs       → ECS Scheduled Tasks or Lambda (if under 15 min)
  Long-running workers → ECS with SQS trigger

Database:
  PostgreSQL / MySQL   → RDS with Multi-AZ enabled
  Redis cache          → ElastiCache (Redis)
  File storage         → S3 with CloudFront CDN
  Search               → OpenSearch Service

Networking:
  Load balancing       → Application Load Balancer (ALB)
  DNS                  → Route 53
  CDN                  → CloudFront
  Secrets              → AWS Secrets Manager (never hardcode credentials)

Phase 3: Infrastructure as Code (Non-Negotiable)

If you're clicking through the AWS console to set up production infrastructure, you're building technical debt with every click. Use Terraform or AWS CDK from day one.

# terraform/main.tf: example: ECS cluster + RDS
resource "aws_ecs_cluster" "app" {
  name = "${var.app_name}-${var.environment}"

  setting {
    name  = "containerInsights"
    value = "enabled"
  }
}

resource "aws_db_instance" "postgres" {
  identifier        = "${var.app_name}-${var.environment}"
  engine            = "postgres"
  engine_version    = "15.3"
  instance_class    = var.db_instance_class
  allocated_storage = var.db_storage_gb

  multi_az               = var.environment == "production"
  deletion_protection    = var.environment == "production"
  backup_retention_period = 7

  db_subnet_group_name   = aws_db_subnet_group.main.name
  vpc_security_group_ids = [aws_security_group.rds.id]
}

Infrastructure as code means your entire environment is reproducible, reviewable in PRs, and recoverable after a disaster.

Phase 4: The Actual Migration

Database migration approach:

For minimal downtime, use the strangler pattern:

Set up RDS instance and run a full dump/restore to establish the baseline
Enable continuous replication from old DB to RDS (AWS DMS handles this)
Run both databases in parallel, validate data consistency
Switch application read traffic to RDS, keep writes going to old DB
Switch write traffic to RDS
Monitor for 48 hours
Decommission old database

Zero-downtime deployment setup:

# ECS task definition snippet
{
  "family": "app-production",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "your-account.dkr.ecr.us-east-1.amazonaws.com/app:latest",
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      }
    }
  ],
  "requiresCompatibilities": ["FARGATE"]
}

The health check is critical. ECS won't route traffic to a new container until it passes. Meaning a bad deployment rolls back automatically instead of taking down production.

Phase 5: Post-Migration Validation

[ ] Response times at or below pre-migration baseline
[ ] Error rates within normal range for 72 hours
[ ] Database query performance profiled on RDS: Slow query log enabled
[ ] CloudWatch alarms configured for: CPU, memory, database connections, error rates, 5xx responses
[ ] Cost Explorer reviewed: Confirm you're not running over-provisioned instances
[ ] Security: all services in private subnets, no public RDS endpoints, WAF in front of ALB
[ ] Backup restore tested: Not just that backups run, but that you can actually restore from them

The Cost Trap

AWS costs can surprise teams coming from fixed-price hosting. Two common traps:

Data transfer costs: Moving data out of AWS is expensive. If your app serves large files to US users, price your CloudFront distribution vs direct S3 transfer costs before you launch.

RDS instance sizing: Teams often start with a db.r6g.4xlarge "to be safe" and pay $800+/month for a database handling 10 req/sec. Start smaller, enable Performance Insights, and scale based on actual metrics, not fear.

Cloud migration done right leaves you with infrastructure that's more reliable, more scalable, and often cheaper than what you started with. Done wrong, it's an expensive, slower version of what you had before.

If you're planning a cloud migration for a US business application, this is core work I do. From architecture planning through live cutover. More at waqarhabib.com/services/cloud-migration.

Originally published at waqarhabib.com

I'm Waqar Habib Khan: A Full-Stack Developer & Fractional CTO for US Startups

Waqar Habib — Thu, 19 Mar 2026 05:40:13 +0000

If you've landed on my profile, you're probably a founder, CTO, or senior engineer
looking for one of three things:

Deep technical content on SaaS, React, Node.js, and cloud architecture
A senior developer or Fractional CTO to work with on a US-market product
Both

Either way, welcome. Let me give you the quick picture.

What I Do

I'm a freelance full-stack developer and Fractional CTO specializing in
SaaS products, API architecture, and cloud infrastructure for the US market.

Over the last several years I've shipped 100+ products across:

SaaS platforms: Multi-tenant architecture, Stripe billing, auth systems, role-based access, usage metering
API development: REST APIs built API-first, versioned, documented, and built to handle US enterprise scale
Cloud infrastructure: AWS and Vercel deployments, Supabase backends, Terraform, zero-downtime CI/CD pipelines
AI integration: LLM-powered features, RAG systems, async AI processing built into production SaaS products
Regulated industries: HIPAA-compliant healthcare apps, PCI DSS FinTech products, FERPA-compliant EdTech platforms

My clients are typically US-based startups from pre-seed through Series B,
and enterprise teams that need senior technical leadership without the
overhead of a full-time hire.

My Stack

Frontend   ->  React, Next.js, TypeScript, Tailwind CSS
Backend    ->  Node.js, Supabase, PostgreSQL, Redis, REST APIs
Cloud      ->  AWS, Vercel, Docker, Terraform, GitHub Actions, CI/CD
AI         ->  OpenAI, LangChain, vector databases, RAG architecture

What I Write About Here

I publish practical, code-heavy articles aimed at developers building
serious products, not toy examples.

Topics I cover regularly:

Node.js architecture: performance, clustering, worker threads, memory management at scale
SaaS engineering: multi-tenancy, billing models, feature flags, pricing schema design
TypeScript in the real world: strict mode, Zod validation, discriminated unions, utility types at scale
API design: REST structure, versioning, contract testing, OpenAPI-first development
Cloud and DevOps: AWS and Vercel deployment patterns, Supabase architecture, GitHub Actions CI/CD without a DevOps team
AI integration: practical LLM patterns, RAG, async job queues for AI features in production SaaS
Regulated tech: HIPAA, PCI DSS, FERPA and what they actually require from developers, not lawyers

No padding. No "in this article we will explore." Just the patterns,
the code, and the reasoning behind both.

Working Together

If you're building a SaaS product, scaling a Node.js backend,
architecting on Supabase or Vercel, migrating to AWS, or need
a senior technical voice in the room without hiring a full-time
CTO, that's exactly the kind of work I take on.

US clients, UK clients, remote. I've done all of it.

The fastest way to reach me:

🌐 waqarhabib.com
📧 contact@waqarhabib.com
💬 Drop a comment below. I read and reply to everything.

One Last Thing

If you're a developer who's read this far, follow along.
I share the patterns and architecture decisions that took me
years of production work to learn.

No courses. No cohorts. Just the real stuff, in public, for free.

Hit Follow at the top of my profile and I'll see you in the feed.

Waqar Habib, Full-Stack Developer and Fractional CTO
waqarhabib.com · contact@waqarhabib.com · USA and UK