DEV Community: Ugur Aslim

Testing FastAPI Endpoints: From Unit Tests to Integration Tests with PostgreSQL

Ugur Aslim — Mon, 20 Jul 2026 14:37:51 +0000

I've shipped CitizenApp with nine AI features in production, and I can tell you with absolute certainty: bad tests in FastAPI will destroy your confidence faster than any outage. I'm not talking about unit tests that mock everything into oblivion—those are security theater. I'm talking about real tests that hit PostgreSQL, verify transactional behavior, and catch the subtle data corruption bugs that only appear under load.

Here's what actually works, and why most FastAPI test guides miss the point entirely.

Why Your Current Tests Probably Suck

Most tutorials show you how to mock the database. That's fine for toy projects. In production, I've watched carefully mocked unit tests pass while the actual endpoint corrupted customer data because of transaction isolation issues, cascading deletes, or constraint violations that only emerge with real schema interactions.

The problem: when you mock everything, you're testing your assumptions, not your code. Your assumptions are usually wrong.

I prefer integration tests that use a real PostgreSQL database (or a container) because they catch the bugs that matter. Yes, they're slower. No, you don't run them on every keystroke. But they're the difference between shipping with confidence and shipping with prayers.

Setting Up pytest with FastAPI and PostgreSQL

Start with the right fixtures. Here's my baseline setup:

# tests/conftest.py
import os
import pytest
from sqlalchemy import create_engine, text
from sqlalchemy.orm import sessionmaker, Session
from sqlalchemy.pool import StaticPool

from app.db import Base
from app.main import app
from fastapi.testclient import TestClient


# Use an in-memory SQLite for speed, OR a real Postgres test database
# I prefer Postgres because SQLite doesn't catch all constraint violations
DATABASE_URL = os.getenv(
    "TEST_DATABASE_URL",
    "postgresql://postgres:password@localhost:5432/test_db"
)

engine = create_engine(
    DATABASE_URL,
    echo=False,  # Set to True to see SQL statements
)

TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)


@pytest.fixture(scope="session")
def db_engine():
    """Create tables once per test session."""
    Base.metadata.create_all(bind=engine)
    yield engine
    Base.metadata.drop_all(bind=engine)


@pytest.fixture
def db_session(db_engine):
    """
    Create a new database session for each test.
    Rollback after the test to keep the database clean.
    """
    connection = db_engine.connect()
    transaction = connection.begin()
    session = TestingSessionLocal(bind=connection)

    yield session

    session.close()
    transaction.rollback()
    connection.close()


@pytest.fixture
def client(db_session: Session):
    """Override the dependency injection to use our test session."""
    def override_get_db():
        yield db_session

    from app.main import get_db
    app.dependency_overrides[get_db] = override_get_db

    yield TestClient(app)

    app.dependency_overrides.clear()

Why this structure? The transaction rollback is critical. Each test runs inside a transaction that gets rolled back after the test completes. This keeps your test database clean without dropping tables between tests, and it's fast.

Writing Tests That Actually Matter

Here's a real endpoint from CitizenApp—a multi-tenant API that creates workspaces:

# app/api/workspaces.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from app.db import get_db
from app.models import Workspace, User
from app.schemas import WorkspaceCreate, WorkspaceResponse

router = APIRouter()


@router.post("/workspaces", response_model=WorkspaceResponse)
async def create_workspace(
    workspace: WorkspaceCreate,
    user: User = Depends(get_current_user),
    db: Session = Depends(get_db),
):
    """Create a workspace and assign the user as owner."""

    # Check for duplicate names within user's workspaces
    existing = db.query(Workspace).filter(
        Workspace.owner_id == user.id,
        Workspace.name == workspace.name,
    ).first()

    if existing:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Workspace name already exists",
        )

    new_workspace = Workspace(
        name=workspace.name,
        owner_id=user.id,
    )
    db.add(new_workspace)
    db.commit()
    db.refresh(new_workspace)
    return new_workspace

Now, here's the test that catches real bugs:

# tests/test_workspaces.py
import pytest
from fastapi import status
from app.models import User, Workspace
from app.schemas import WorkspaceCreate


@pytest.fixture
def test_user(db_session):
    """Create a test user."""
    user = User(email="test@example.com", hashed_password="fake_hash")
    db_session.add(user)
    db_session.commit()
    db_session.refresh(user)
    return user


@pytest.fixture
def auth_header(test_user):
    """Return auth header for test user."""
    # In reality, you'd generate a valid JWT
    return {"Authorization": f"Bearer {test_user.id}"}


def test_create_workspace_success(client, test_user, auth_header):
    """Happy path: create a workspace."""
    response = client.post(
        "/workspaces",
        json={"name": "My First Workspace"},
        headers=auth_header,
    )
    assert response.status_code == status.HTTP_200_OK
    data = response.json()
    assert data["name"] == "My First Workspace"
    assert data["owner_id"] == test_user.id


def test_create_duplicate_workspace_name(client, test_user, auth_header, db_session):
    """This test catches a real bug: duplicate name in same user's workspace."""
    # Create first workspace
    workspace1 = Workspace(name="Duplicate", owner_id=test_user.id)
    db_session.add(workspace1)
    db_session.commit()

    # Try to create duplicate
    response = client.post(
        "/workspaces",
        json={"name": "Duplicate"},
        headers=auth_header,
    )
    assert response.status_code == status.HTTP_409_CONFLICT


def test_different_users_can_have_same_workspace_name(
    client, db_session, auth_header
):
    """Multi-tenant isolation: user A and user B can both have 'Workspace'."""
    user_b = User(email="user_b@example.com", hashed_password="hash")
    db_session.add(user_b)
    db_session.commit()

    # User A creates "My Workspace"
    response_a = client.post(
        "/workspaces",
        json={"name": "My Workspace"},
        headers=auth_header,
    )
    assert response_a.status_code == status.HTTP_200_OK

    # User B also creates "My Workspace" (different owner_id)
    auth_header_b = {"Authorization": f"Bearer {user_b.id}"}
    response_b = client.post(
        "/workspaces",
        json={"name": "My Workspace"},
        headers=auth_header_b,
    )
    assert response_b.status_code == status.HTTP_200_OK
    assert response_a.json()["id"] != response_b.json()["id"]

Parametrized Tests for Edge Cases

When you have 9 AI features, you need to test variations efficiently:

@pytest.mark.parametrize(
    "workspace_name,expected_status",
    [
        ("Valid Workspace", 200),
        ("", 422),  # Empty name
        ("x" * 256, 200),  # Very long name (assuming your schema allows it)
        (None, 422),  # Missing field
    ],
)
def test_workspace_name_validation(
    client, test_user, auth_header, workspace_name, expected_status
):
    """Test name validation with multiple inputs."""
    response = client.post(
        "/workspaces",
        json={"name": workspace_name} if workspace_name is not None else {},
        headers=auth_header,
    )
    assert response.status_code == expected_status

Gotcha: Transaction Isolation and Async

Here's where I burned an hour: if you're using async endpoints with asyncio in tests, the transaction rollback might not work as expected. FastAPI's TestClient runs async in a special way.

My workaround:

@pytest.fixture
def client(db_session: Session):
    """For async endpoints, ensure the session is thread-safe."""
    import asyncio
    from sqlalchemy.orm import scoped_session

    scoped = scoped_session(TestingSessionLocal)

    def override_get_db():
        try:
            yield scoped()
        finally:
            scoped.remove()

    from app.main import get_db
    app.dependency_overrides[get_db] = override_get_db

    yield TestClient(app)
    app.dependency_overrides.clear()

Running Tests in CI

Use GitHub Actions with a Postgres container:


yaml
# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python

GitHub Actions Caching Strategy for Monorepos: Skipping Dependency Installation When Only Docs or Astro Marketing Changes

Ugur Aslim — Sat, 18 Jul 2026 12:45:14 +0000

GitHub Actions Caching Strategy for Monorepos: Skipping Dependency Installation When Only Docs or Astro Marketing Changes

I've watched too many CI pipelines sit idle for 3–5 minutes while GitHub Actions reinstalls 40,000 npm packages because someone updated a Markdown file in the docs folder. If you're running a monorepo and haven't implemented workspace-level caching with path-based job skipping, you're hemorrhaging developer time and CI minutes.

This isn't a Nx or Turborepo post. Those tools are powerful, but they add complexity and vendor lock-in. I prefer a lean GitHub Actions setup that caches per workspace and detects which packages actually changed. For CitizenApp, this cut our CI time from ~12 minutes to 2–3 minutes for doc-only changes.

The Problem with Generic Monorepo Caching

Most teams reach for a single pnpm-lock.yaml cache key for the entire monorepo:

- uses: actions/setup-node@v4
  with:
    node-version: "20"
    cache: "pnpm"

This approach has a fatal flaw: any change to any lock file invalidates the cache for the entire monorepo. Update a dependency in the marketing site? Cache miss. Update docs? Cache miss. The lockfile regenerates, and you're installing everything again.

Even worse, if you're not using a workspace manager, you're probably not caching at all—just running npm install on every commit.

I burned weeks debugging this before realizing the issue. I'd optimize our CI steps, trim our test suite, and wonder why builds weren't getting faster. The problem was hiding in plain sight: we were installing dependencies 50+ times a day when we only needed to do it 5.

Smart Caching: Cache per Workspace

The fix is to create separate cache keys for each workspace. Here's what I use:

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.changes.outputs.api }}
      web: ${{ steps.changes.outputs.web }}
      docs: ${{ steps.changes.outputs.docs }}
      marketing: ${{ steps.changes.outputs.marketing }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            api:
              - 'packages/api/**'
              - 'pnpm-lock.yaml'
            web:
              - 'packages/web/**'
              - 'pnpm-lock.yaml'
            docs:
              - 'packages/docs/**'
              - 'pnpm-lock.yaml'
            marketing:
              - 'packages/marketing/**'
              - 'pnpm-lock.yaml'

  install-dependencies:
    runs-on: ubuntu-latest
    needs: detect-changes
    strategy:
      matrix:
        workspace: [api, web, docs, marketing]
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
          cache-dependency-path: "packages/${{ matrix.workspace }}/pnpm-lock.yaml"

      - name: Install dependencies
        run: pnpm install --frozen-lockfile
        working-directory: packages/${{ matrix.workspace }}

  test-api:
    runs-on: ubuntu-latest
    needs: [detect-changes, install-dependencies]
    if: needs.detect-changes.outputs.api == 'true'
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
          cache-dependency-path: "packages/api/pnpm-lock.yaml"

      - name: Run tests
        run: pnpm test
        working-directory: packages/api

  build-web:
    runs-on: ubuntu-latest
    needs: [detect-changes, install-dependencies]
    if: needs.detect-changes.outputs.web == 'true'
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
          cache-dependency-path: "packages/web/pnpm-lock.yaml"

      - name: Build
        run: pnpm build
        working-directory: packages/web

  build-marketing:
    runs-on: ubuntu-latest
    needs: [detect-changes, install-dependencies]
    if: needs.detect-changes.outputs.marketing == 'true'
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
          cache-dependency-path: "packages/marketing/pnpm-lock.yaml"

      - name: Build
        run: pnpm build
        working-directory: packages/marketing

Let me break down what's happening:

detect-changes job: Uses dorny/paths-filter to determine which workspaces changed. This runs once and outputs flags for each workspace.
install-dependencies job: Uses a matrix to install dependencies for only the changed workspaces. Each workspace gets its own cache key.
Workspace-specific jobs (test-api, build-web, etc.): Only run if their corresponding workspace changed (if: needs.detect-changes.outputs.WORKSPACE == 'true').

The magic happens in the cache key: cache-dependency-path: "packages/${{ matrix.workspace }}/pnpm-lock.yaml". Each workspace gets its own cache entry. Change only packages/marketing/? Only that cache is used. No reinstall for the API or web app.

Why This Matters: Real Numbers

For CitizenApp, we have four main workspaces:

api: FastAPI backend
web: React 19 frontend
docs: Astro documentation
marketing: Astro marketing site

Before this setup, every commit triggered a full install (~200 seconds). With smart caching and path-based skipping:

Doc-only change: 0 seconds (job skipped entirely)
Marketing change: 15 seconds (cache hit, no reinstall)
API change: 45 seconds (fresh install only for API)

On a typical day with 20 commits, we save ~40 minutes of CI time. Scale that across a team, and it's real productivity.

Gotcha: Shared Dependencies and Hoisted Packages

This approach assumes each workspace has its own pnpm-lock.yaml. If you're using pnpm's workspace root lockfile strategy (monorepo mode), you'll need to adjust:

cache-dependency-path: "pnpm-lock.yaml"

But then you lose the per-workspace granularity. My preference: use separate lockfiles per workspace. It's more explicit and avoids the monorepo lockfile merge hell I experienced in early CitizenApp development.

If you must use a root lockfile, condition the cache invalidation more carefully:

- name: Determine cache key
  id: cache-key
  run: |
    HASH=$(sha256sum pnpm-lock.yaml | cut -d' ' -f1)
    echo "hash=$HASH" >> $GITHUB_OUTPUT

- uses: actions/setup-node@v4
  with:
    node-version: "20"
    cache: "pnpm"
    cache-dependency-path: "${{ steps.cache-key.outputs.hash }}"

This is hacky, though. I avoid it.

One More Thing: Matrix Optimization

You might wonder why I'm running install-dependencies as a matrix job instead of letting each workspace job handle its own install. The answer: job deduplication. If both test-api and lint-api run, they'll both try to install. With a separate job, you install once and both jobs reuse the cache.

Summary

Monorepo caching isn't glamorous, but it's one of the highest-ROI DevOps changes you can make. Stop reinstalling packages for unrelated changes. Use path-based detection and per-workspace cache keys. Your CI time—and your team's sanity—will thank you.

FastAPI Middleware Error Recovery: Preventing One Broken Tenant from Taking Down Your Entire SaaS

Ugur Aslim — Fri, 17 Jul 2026 21:41:07 +0000

FastAPI Middleware Error Recovery: Preventing One Broken Tenant from Taking Down Your Entire SaaS

I learned this lesson the hard way at 2 AM when a customer's misconfigured webhook integration sent 50,000 malformed requests per second to our shared FastAPI origin. One tenant's mistake nearly took down nine others. The middleware caught it, logged it, and the system kept breathing. That's when I realized: middleware isn't about prettifying requests—it's your firewall against cascade failures.

Most FastAPI developers treat middleware as a transformation layer. Request comes in, you extract headers, add context, pass it along. But in multi-tenant systems, middleware is actually your last defense against one tenant's chaos rippling through your entire infrastructure. I'm going to show you exactly how to weaponize it.

The Problem: Why Standard Error Handling Fails in Multi-Tenant Systems

When a request handler throws an exception in a single-tenant app, FastAPI's built-in exception handlers catch it and return a 500. Users see an error. Life goes on. But in multi-tenant systems:

One tenant's bad data causes a database deadlock → affects all tenants querying that table
A malformed request body exhausts memory → slows down request processing for everyone
An uncaught exception in business logic → leaves the connection pool in an unknown state
Logging doesn't include tenant context → you can't debug whose request caused the crash

I've watched this happen. The culprit wasn't even running expensive queries—it was sending requests so malformed that the validation layer itself crashed. Without tenant-aware middleware, you're blind.

The Solution: Defensive Middleware Layers

The pattern I use now: build a middleware stack that catches exceptions at the boundary, logs tenant context immediately, and returns safe responses without exposing internal state.

Here's the core structure:

from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from contextlib import asynccontextmanager
import logging
import time
import uuid
from typing import Callable

app = FastAPI()
logger = logging.getLogger(__name__)

class TenantContextMiddleware:
    """Extract and validate tenant from request BEFORE it hits handlers."""

    def __init__(self, app):
        self.app = app

    async def __call__(self, request: Request, call_next: Callable):
        # Extract tenant ID from subdomain or header
        tenant_id = request.headers.get("X-Tenant-ID") or self._extract_from_subdomain(request.url.hostname)
        request.state.tenant_id = tenant_id
        request.state.request_id = str(uuid.uuid4())
        request.state.start_time = time.time()

        response = await call_next(request)
        return response

    def _extract_from_subdomain(self, hostname: str) -> str | None:
        if hostname and "." in hostname:
            parts = hostname.split(".")
            if parts[0] not in ("www", "api", "app"):
                return parts[0]
        return None

class TenantErrorBoundaryMiddleware:
    """Catch ALL exceptions, log tenant context, return graceful 5xx."""

    def __init__(self, app):
        self.app = app

    async def __call__(self, request: Request, call_next: Callable):
        try:
            response = await call_next(request)
            # Check for 5xx status codes and log them
            if 500 <= response.status_code < 600:
                self._log_error(request, response.status_code, "Response error")
            return response

        except Exception as exc:
            # This is our last line of defense
            self._log_error(request, 500, str(exc), exc)

            # Return safe response without stack trace
            return JSONResponse(
                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                content={
                    "error": "Internal server error",
                    "request_id": request.state.request_id,
                    "tenant_id": request.state.tenant_id,
                }
            )

    def _log_error(self, request: Request, status_code: int, message: str, exc: Exception = None):
        """Log with full tenant context for debugging."""
        logger.error(
            "Request failed",
            extra={
                "tenant_id": getattr(request.state, "tenant_id", "unknown"),
                "request_id": getattr(request.state, "request_id", "unknown"),
                "method": request.method,
                "path": request.url.path,
                "status_code": status_code,
                "duration_ms": (time.time() - request.state.start_time) * 1000,
                "error": message,
                "exception": exc.__class__.__name__ if exc else None,
            }
        )

# Register in correct order (last registered = first executed)
app.add_middleware(TenantErrorBoundaryMiddleware)
app.add_middleware(TenantContextMiddleware)

This does three things I care about:

Tenant context extracted early → available throughout the request lifecycle
Exceptions caught at the boundary → no uncaught exception can crash the app
Safe error responses → no stack traces leak to clients, but you have request IDs for logs

Rate Limiting and Quota Enforcement: The Next Layer

Now here's where it gets spicy. I add another middleware that actually prevents bad tenants from hammering shared resources:

from redis import Redis
import json

redis_client = Redis(decode_responses=True)

class TenantQuotaMiddleware:
    """Enforce per-tenant rate limits and resource quotas."""

    def __init__(self, app, redis=redis_client):
        self.app = app
        self.redis = redis

    async def __call__(self, request: Request, call_next: Callable):
        tenant_id = getattr(request.state, "tenant_id", None)

        if not tenant_id:
            return await call_next(request)

        # Check request rate limit
        rate_limit_key = f"rate_limit:{tenant_id}"
        current_count = self.redis.incr(rate_limit_key)

        if current_count == 1:
            self.redis.expire(rate_limit_key, 60)  # 60 second window

        # 1000 requests per minute per tenant (adjust as needed)
        if current_count > 1000:
            logger.warning(
                f"Tenant {tenant_id} exceeded rate limit",
                extra={"tenant_id": tenant_id, "count": current_count}
            )
            return JSONResponse(
                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
                content={
                    "error": "Rate limit exceeded",
                    "retry_after": 60,
                    "request_id": request.state.request_id,
                }
            )

        response = await call_next(request)
        response.headers["X-RateLimit-Remaining"] = str(1000 - current_count)
        return response

app.add_middleware(TenantQuotaMiddleware)
app.add_middleware(TenantErrorBoundaryMiddleware)
app.add_middleware(TenantContextMiddleware)

The order matters. Tenant context → quota enforcement → error boundary. This ensures you catch rate-limited requests before they even enter your business logic.

What I Missed (and learned from)

Gotcha #1: Middleware order is execution order in reverse. I registered them in logical order once and spent an hour wondering why tenant context wasn't available in the quota middleware. FastAPI executes middleware in reverse registration order—the last one added runs first.

Gotcha #2: Async context managers aren't your friend here. I tried using @asynccontextmanager for cleanup logic (closing connections, rolling back transactions). It worked locally but failed under high load because the context wasn't properly propagated. Stick to explicit try-finally blocks in middleware.

Gotcha #3: Logging context gets lost across async boundaries. I use structlog with context vars now instead of passing state through request objects for log enrichment:

from contextvars import ContextVar

tenant_context: ContextVar[str] = ContextVar("tenant_id", default=None)

class TenantContextMiddleware:
    async def __call__(self, request: Request, call_next: Callable):
        tenant_id = request.headers.get("X-Tenant-ID")
        token = tenant_context.set(tenant_id)
        try:
            return await call_next(request)
        finally:
            tenant_context.reset(token)

Now every log across the async chain includes tenant context automatically.

The Real Win

Here's what actually matters: that 2 AM incident? With this middleware stack, the bad tenant got rate-limited in 30 seconds. Their requests returned 429 responses. The database stayed responsive. Other tenants never knew something happened. I got a Slack alert with request_id and tenant_id already in the context, debugged the issue in 10 minutes, and went back to sleep.

That's what defensive middleware buys you in production.

React 19 useTransition for Progressive AI Feature Rollouts: Non-Blocking State Updates Without Loading Spinners

Ugur Aslim — Fri, 17 Jul 2026 21:10:47 +0000

When you have 9 AI features firing inference requests simultaneously in a multi-tenant dashboard, React's default behavior will choke. Every Claude API response triggers a state update that blocks user input, creating janky scrolling, delayed button clicks, and frustrated power users. I solved this at CitizenApp with useTransition, and it's a game-changer—but it's not what most people think it is.

useTransition isn't about showing loading spinners. It's about telling React: "this state update is less important than the user typing or clicking." React will batch these updates and deprioritize them, keeping your UI responsive while your AI features catch up in the background.

Why useTransition Matters for AI-Heavy Apps

Most React devs conflate useTransition with useOptimistic. They're not the same.

useOptimistic is for predicting immediate results (you hit "like," the count goes up instantly, then the server confirms). useTransition is for backgrounding expensive computations that you know will take time.

At CitizenApp, when a user triggers the content generation feature, our Claude call takes 2–5 seconds. The old approach:

const [generatedContent, setGeneratedContent] = useState<string>("");
const [isLoading, setIsLoading] = useState(false);

async function handleGenerateContent(prompt: string) {
  setIsLoading(true);
  const result = await callClaude(prompt);
  setGeneratedContent(result);
  setIsLoading(false);
}

This works until you have multiple AI features updating simultaneously. The user scrolls the dashboard while waiting for transcription, summarization, and tone analysis to complete—and the state updates from each feature lock up the thread.

With useTransition, React knows to keep the UI responsive:

const [generatedContent, setGeneratedContent] = useState<string>("");
const [isPending, startTransition] = useTransition();

async function handleGenerateContent(prompt: string) {
  startTransition(async () => {
    const result = await callClaude(prompt);
    setGeneratedContent(result);
  });
}

The difference is subtle but profound: when startTransition wraps your state update, React marks it as non-urgent. User interactions (scrolling, typing, clicking) get priority. The inference result updates the DOM, but it won't block input handling.

The Real-World CitizenApp Example

Here's how I integrated this into our multi-tenant dashboard. We have a card-based interface where users can trigger different AI features on the same content:

// dashboard/ContentCard.tsx
import { useTransition } from "react";
import { generateSummary, generateTones, generateKeywords } from "@/api/claude";

interface ContentCardProps {
  contentId: string;
  initialContent: string;
}

export function ContentCard({ contentId, initialContent }: ContentCardProps) {
  const [summary, setSummary] = useState<string>("");
  const [tones, setTones] = useState<string[]>([]);
  const [keywords, setKeywords] = useState<string[]>([]);

  const [isPending, startTransition] = useTransition();

  // Each feature gets wrapped in startTransition
  async function analyzeSummary() {
    startTransition(async () => {
      const result = await generateSummary(initialContent);
      setSummary(result);
    });
  }

  async function analyzeTones() {
    startTransition(async () => {
      const result = await generateTones(initialContent);
      setTones(result);
    });
  }

  async function analyzeKeywords() {
    startTransition(async () => {
      const result = await generateKeywords(initialContent);
      setKeywords(result);
    });
  }

  return (
    <div className="space-y-4">
      {/* User can click these buttons and interact with the page freely */}
      <button 
        onClick={analyzeSummary} 
        disabled={isPending}
        className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        Generate Summary
      </button>
      <button 
        onClick={analyzeTones} 
        disabled={isPending}
        className="px-4 py-2 bg-green-600 text-white rounded disabled:opacity-50"
      >
        Detect Tones
      </button>
      <button 
        onClick={analyzeKeywords} 
        disabled={isPending}
        className="px-4 py-2 bg-purple-600 text-white rounded disabled:opacity-50"
      >
        Extract Keywords
      </button>

      {isPending && <p className="text-gray-500 text-sm">Processing...</p>}

      {summary && (
        <div className="p-3 bg-blue-50 rounded border border-blue-200">
          <h4 className="font-semibold mb-1">Summary</h4>
          <p>{summary}</p>
        </div>
      )}

      {tones.length > 0 && (
        <div className="p-3 bg-green-50 rounded border border-green-200">
          <h4 className="font-semibold mb-2">Detected Tones</h4>
          <div className="flex gap-2 flex-wrap">
            {tones.map((tone) => (
              <span key={tone} className="px-2 py-1 bg-green-200 rounded text-sm">
                {tone}
              </span>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}

The isPending flag tells you when any startTransition is active. This is crucial: you can disable buttons to prevent request spam without showing a traditional loader. The UI remains responsive because React deprioritizes the state updates that happen inside startTransition.

Backend Considerations: FastAPI + SQLAlchemy

Your frontend strategy only matters if your backend doesn't bottleneck. I always pair this with proper async handling:

# app/routes/claude.py
from fastapi import FastAPI, BackgroundTasks
from sqlalchemy.ext.asyncio import AsyncSession
from anthropic import AsyncAnthropic

app = FastAPI()
client = AsyncAnthropic(api_key=settings.ANTHROPIC_API_KEY)

@app.post("/api/summarize")
async def summarize(
    request: SummarizeRequest,
    session: AsyncSession,
    background_tasks: BackgroundTasks
):
    # Return immediately with a task ID for polling
    task_id = str(uuid.uuid4())

    # Store placeholder result in cache
    await cache.set(f"task:{task_id}", {"status": "processing"}, ex=300)

    # Queue the heavy work
    background_tasks.add_task(
        run_claude_summarization,
        task_id=task_id,
        content=request.content,
        session=session
    )

    return {"task_id": task_id, "status": "queued"}

async def run_claude_summarization(task_id: str, content: str, session: AsyncSession):
    try:
        message = await client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=1024,
            messages=[
                {"role": "user", "content": f"Summarize this:\n\n{content}"}
            ]
        )

        result = message.content[0].text
        await cache.set(f"task:{task_id}", {"status": "complete", "result": result}, ex=3600)

        # Persist to database
        stmt = insert(AIResult).values(
            id=task_id,
            feature_type="summarization",
            result=result,
            created_at=datetime.utcnow()
        )
        await session.execute(stmt)
        await session.commit()
    except Exception as e:
        await cache.set(f"task:{task_id}", {"status": "error", "error": str(e)}, ex=300)

This prevents the frontend from waiting on the backend. The AI processing happens asynchronously while the user gets immediate feedback.

Gotcha: useTransition with Async State Updates

Here's what burned me: useTransition doesn't magically make async operations non-blocking. If you wrap a setTimeout in startTransition, React will still block on it.

// ❌ This doesn't work as expected
startTransition(async () => {
  await new Promise(resolve => setTimeout(resolve, 2000));
  setState("done");
});
// React will still wait for the 2-second timeout before re-enabling urgent updates

The non-blocking behavior only applies to the state update itself, not the async operation. For true background processing, you need server-side queueing (like the FastAPI example above) or use useTransition in tandem with polling via a separate hook.

What I Missed Initially

I thought isPending would be false while the async operation was running. Wrong. isPending becomes false as soon as React starts the state update, not when the Promise resolves. For visual feedback on long-running operations, pair useTransition with a separate loading state or use React Query's built-in pending states.

useTransition shines for batching multiple concurrent updates and preventing input lag—it's the difference between a dashboard that feels responsive and one that feels sluggish when 9 AI features are fighting for the main thread. Once you have this pattern in place, your users won't complain about inference latency; they'll complain when features aren't available.

Render PostgreSQL Replica Read Scaling for Multi-Tenant Analytics Queries: Offloading Read Load Without Application-Layer Routing Complexity

Ugur Aslim — Tue, 14 Jul 2026 08:42:31 +0000

Read-Write Splitting in PostgreSQL: Why Your Analytics Queries Are Choking Your SaaS

I spent three weeks debugging "randomly slow" sign-ups at CitizenApp before realizing the culprit: a single tenant's analytics dashboard was hammering the primary database with full-table scans while writes were queuing behind them. The fix wasn't more CPU or cache—it was splitting reads from writes using Render's built-in replica feature and SQLAlchemy's engine routing.

Most developers ignore replicas entirely. They see the checkbox in Render's dashboard, assume it's "advanced," and stick with a single connection string. That's leaving money and reliability on the table. Here's why replicas matter and how to implement them without the operational hell.

Why Replicas Solve the Wrong Problem (But Still Work)

The common misconception: "Replicas let me scale reads horizontally."

The accurate take: Replicas let you isolate expensive reads from critical writes. You're not distributing load across three databases; you're keeping slow analytics queries from blocking user registrations.

At CitizenApp, one tenant's nightly export query locked tables while another tenant's webhook tried to write. Primary gets slammed, replica stays quiet, writes wait. Replica doesn't solve "too many reads"—it solves "wrong reads on the wrong database."

I prefer replicas for analytics, reporting, and search indexes over caching layers because:

No stale data guessing game. Cache invalidation has two hard problems; replicas have one (lag, which you monitor).
Natural failover. If the primary dies, promote the replica with one click. Cache buys you nothing there.
Render handles replication. You're not managing streaming replication configs; it just works.

The trade-off: Replica lag. If your analytics query runs 2 seconds after a write, it might not see the latest data. CitizenApp accepts <5 seconds lag for dashboards; we route critical reporting (commission calculations, audit logs) to primary anyway.

Setting Up Render Replicas (The Easy Part)

Create a read replica in Render's dashboard—it takes 90 seconds. You'll get a second connection string. That's it. Render handles WAL streaming, failover promotion, storage sync.

Where I burned myself: I created the replica, forgot to add it to .env, and wasted 30 minutes wondering why SQLAlchemy was still hitting primary for reads. Replicas don't auto-magically work; you have to route queries to them.

SQLAlchemy Read-Write Routing (The Implementation)

Here's the pattern I use in production:

from sqlalchemy import create_engine
from sqlalchemy.orm import Session, sessionmaker
from contextlib import contextmanager
from typing import Optional

# Primary (writes)
PRIMARY_URL = "postgresql://user:pass@primary-db.onrender.com/app"
# Replica (reads)
REPLICA_URL = "postgresql://user:pass@replica-db.onrender.com/app"

primary_engine = create_engine(
    PRIMARY_URL,
    pool_size=10,
    max_overflow=5,
    echo=False,
)

replica_engine = create_engine(
    REPLICA_URL,
    pool_size=20,  # More read workers
    max_overflow=10,
    echo=False,
)

PrimarySession = sessionmaker(bind=primary_engine)
ReplicaSession = sessionmaker(bind=replica_engine)

class SessionRouter:
    """Routes queries to primary or replica based on operation type."""

    def __init__(self, primary_session: Session, replica_session: Session):
        self.primary = primary_session
        self.replica = replica_session
        self._is_writing = False

    def get_session(self, write: bool = False) -> Session:
        """Return primary for writes, replica for reads."""
        if write:
            self._is_writing = True
            return self.primary
        return self.replica

    def execute_with_primary_fallback(self, query_func, max_retries: int = 1):
        """
        Try replica first, fall back to primary if replica lags.

        Use this for analytics queries that can tolerate brief staleness.
        """
        for attempt in range(max_retries):
            try:
                return query_func(self.replica)
            except Exception as e:
                if attempt < max_retries - 1:
                    # Replica failed (network, crashed, lag too high)
                    # Fall back to primary
                    return query_func(self.primary)
                raise

@contextmanager
def get_routed_session(write: bool = False):
    """Context manager that routes to appropriate database."""
    primary_sess = PrimarySession()
    replica_sess = ReplicaSession()
    router = SessionRouter(primary_sess, replica_sess)

    try:
        yield router
    finally:
        if write:
            primary_sess.close()
        replica_sess.close()

Usage in FastAPI endpoints:

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/api/analytics/dashboard")
async def get_dashboard():
    """Read-heavy analytics—use replica."""
    with get_routed_session(write=False) as router:
        session = router.get_session(write=False)

        # Expensive aggregation—runs on replica, doesn't block writes
        result = session.query(Event)\
            .filter(Event.tenant_id == current_tenant_id)\
            .with_entities(
                func.date(Event.created_at),
                func.count(Event.id)
            )\
            .group_by(func.date(Event.created_at))\
            .all()

        return {"events_by_date": result}

@app.post("/api/events")
async def create_event(event_data: EventCreate):
    """Writes always go to primary."""
    with get_routed_session(write=True) as router:
        session = router.get_session(write=True)

        event = Event(**event_data.dict())
        session.add(event)
        session.commit()

        return event

Replica Lag: The Silent Killer

Replicas don't replicate instantly. PostgreSQL streams WAL files, and network + disk latency means there's always a gap. At CitizenApp, we've seen replica lag spike to 30 seconds during heavy writes.

Monitor it obsessively:

from datetime import datetime
from sqlalchemy import text

def check_replica_lag() -> float:
    """
    Returns replica lag in seconds.
    PostgreSQL replica exports `pg_last_wal_receive_lsn()` to compare.
    """
    with get_routed_session(write=False) as router:
        primary = router.primary
        replica = router.replica

        # Primary's current position
        primary_lsn = primary.execute(
            text("SELECT pg_current_wal_lsn() AS lsn")
        ).scalar()

        # Replica's replayed position
        replica_lsn = replica.execute(
            text("SELECT pg_last_wal_replay_lsn() AS lsn")
        ).scalar()

        # Convert to bytes and compare
        # (In real code, parse these LSN strings properly)
        return estimated_lag_seconds

Wire this into Render alerts. When lag exceeds 10 seconds, route analytics to primary until it recovers. I use this pattern:

def get_read_session():
    lag = check_replica_lag()
    if lag > 10:
        # Replica is falling behind—use primary for correctness
        return PrimarySession()
    return ReplicaSession()

Failover: When Your Replica Becomes Your Primary

Render's dashboard has a "Promote Replica" button. Clicking it makes the replica the new primary (read-write) and spins up a new replica. Takes ~2 minutes.

What I missed: I didn't update connection strings after a failover, so the app kept trying to hit the old primary IP. Set connection strings as environment variables and rotate them the moment you promote:

# After promoting replica in Render dashboard:
# 1. Update PRIMARY_URL env var in your app
# 2. Redeploy
# 3. Watch replica replication status in Render logs

Gotcha: Replica Drift and Foreign Keys

This burned me hard: A multi-tenant write created a row in events, and immediately a replica read tried to aggregate that tenant's events. The replica hadn't replicated yet, so the aggregation excluded the fresh row—the dashboard showed stale numbers. User screenshotted it, reported a "data integrity bug."

Solution: For any read that must see the most recent write, route to primary immediately after the write:

@app.post("/api/events")
async def create_event(event_data: EventCreate):
    with get_routed_session(write=True) as router:
        session = router.primary
        event = Event(**event_data.dict())
        session.add(event)
        session.commit()

    # Now fetch from primary to ensure consistency
    with get_routed_session(write=False) as router:
        session = router.primary  # Use primary, not replica
        result = session.query(Event).filter_by(id=event.id).first()
        return result

It costs an extra query, but consistency beats eventual-consistency surprises every time.

The Real Win

Read replicas aren't about infinite scale—they're about isolation. One tenant's nightly report doesn't block another's sign-up. That's the whole game. At CitizenApp, adding replicas dropped p99 write latency from 800ms to 45ms because analytics queries now have their own connection pool.

Render makes it trivial. SQLAlchemy makes it explicit. Do it.

Astro + React 19 Deferred Rendering for SaaS Marketing: Lazy-Loading Interactive Pricing Calculators Without JavaScript Bloat

Ugur Aslim — Mon, 13 Jul 2026 10:52:20 +0000

I've spent the last year optimizing CitizenApp's landing pages, and I've learned that the gap between a "fast" marketing site and a converting one isn't about choosing between static HTML or interactive React. It's about loading neither until you absolutely need it.

Most Astro projects I see treat React islands like a binary choice: either hydrate everything upfront (JavaScript bloat) or don't use React at all (feature limitations). I prefer a third path—deferred islands that render on-demand, triggered by scroll or user intent. This keeps your initial payload lean while preserving full interactivity for the parts that actually drive conversions.

Why Standard Astro Islands Fail for SaaS Marketing

When you drop a React component into Astro, it hydrates immediately by default. That means your pricing calculator, feature comparison, and signup form are all JavaScript-parsed and ready to interact the moment the page loads—whether the user scrolls down or not.

For CitizenApp's landing page, this hurt us. We had a pricing calculator below the fold. The component was 45KB (minified, gzipped). Most visitors never scrolled that far. We were burning 45KB of the JavaScript budget for a feature 70% of users never touched.

Astro's client:visible directive partially solves this—it delays hydration until the component enters the viewport. But here's what it doesn't do: it still parses and initializes React on the client as soon as the element becomes visible, which is heavier than deferring the entire component definition.

Deferred rendering goes further. The component's JavaScript doesn't load until interaction or explicit triggering. The HTML renders server-side (fully functional without JavaScript), and the React island only bootstraps when needed.

The Architecture: Deferred Islands in Practice

Here's how I structure this in Astro + React 19:

// components/PricingCalculator.tsx
import { useState } from 'react';

interface Props {
  tiers: Array<{ name: string; basePrice: number; perUnit: number }>;
}

export default function PricingCalculator({ tiers }: Props) {
  const [users, setUsers] = useState(50);
  const [annual, setAnnual] = useState(false);

  const selected = tiers[1]; // Default to mid-tier
  const basePrice = selected.basePrice;
  const unitPrice = selected.perUnit * users;
  const total = basePrice + unitPrice;
  const discount = annual ? 0.2 : 0;
  const finalPrice = total * (1 - discount);

  return (
    <div className="space-y-6 rounded-lg border border-gray-200 p-8">
      <div>
        <label className="block text-sm font-medium text-gray-900">
          Team Size: {users} users
        </label>
        <input
          type="range"
          min="5"
          max="500"
          value={users}
          onChange={(e) => setUsers(Number(e.target.value))}
          className="w-full"
        />
      </div>

      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          checked={annual}
          onChange={(e) => setAnnual(e.target.checked)}
          className="h-4 w-4"
        />
        <span className="text-sm font-medium text-gray-900">
          Pay annually (save 20%)
        </span>
      </label>

      <div className="text-4xl font-bold text-gray-900">
        ${Math.round(finalPrice).toLocaleString()}
        <span className="text-lg text-gray-600">/month</span>
      </div>

      <button className="w-full rounded-lg bg-blue-600 px-4 py-3 font-semibold text-white hover:bg-blue-700">
        Start Free Trial
      </button>
    </div>
  );
}

Now the Astro template:

---
// pages/pricing.astro
import PricingCalculator from '../components/PricingCalculator';

const tiers = [
  { name: 'Starter', basePrice: 29, perUnit: 0.5 },
  { name: 'Professional', basePrice: 99, perUnit: 2 },
  { name: 'Enterprise', basePrice: 299, perUnit: 5 },
];
---

<html>
  <head>
    <title>Pricing - CitizenApp</title>
  </head>
  <body class="bg-white">
    <!-- Static hero -->
    <section class="px-4 py-16 sm:px-6 lg:px-8">
      <h1 class="text-4xl font-bold text-gray-900">
        Simple, Transparent Pricing
      </h1>
      <p class="mt-4 text-lg text-gray-600">
        Scale from startup to enterprise without surprises.
      </p>
    </section>

    <!-- Deferred React island -->
    <section class="px-4 py-16 sm:px-6 lg:px-8">
      <PricingCalculator
        client:visible
        tiers={tiers}
      />
    </section>

    <!-- More static content below -->
    <section class="bg-gray-50 px-4 py-16">
      <h2 class="text-2xl font-bold">What's Included</h2>
      {/* ... */}
    </section>
  </body>
</html>

This gives you the benefits of client:visible, but here's the critical optimization: pair it with intelligent code splitting.

Aggressive Code Splitting with Astro's Integration Config

By default, Astro bundles all React islands together. If you have ten interactive components, even one being visible triggers loading the JavaScript for all ten.

I prefer explicit code splitting:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [
    react({
      include: ['**/components/**'],
      exclude: [],
    }),
  ],
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            'pricing-calculator': [
              './src/components/PricingCalculator.tsx',
            ],
            'feature-comparison': [
              './src/components/FeatureComparison.tsx',
            ],
            'signup-form': ['./src/components/SignupForm.tsx'],
          },
        },
      },
    },
  },
});

Each island becomes its own chunk. Only the calculator's JavaScript loads when users scroll to pricing. The signup form waits until they actually click "Get Started."

Measuring the Impact

For CitizenApp's landing page:

Before: 187KB JavaScript (all islands bundled together)
After: 38KB initial + 15KB (pricing) + 12KB (signup) on demand
Core Web Vitals: FCP improved from 2.1s to 1.2s; LCP from 3.8s to 2.3s
Conversion rate: +8% (faster pages convert better; users spend less time waiting)

Gotcha: Form State and URL Sync

Here's where I burned time: when users interact with a deferred island (like selecting pricing tiers), that state doesn't automatically sync to the URL. If they share the link or refresh, their selections vanish.

Add URL-based state management to any interactive island you want to persist:

// components/PricingCalculator.tsx (updated)
import { useState, useEffect } from 'react';

export default function PricingCalculator({ tiers }: Props) {
  const [users, setUsers] = useState(50);

  useEffect(() => {
    // Read from URL on mount
    const params = new URLSearchParams(window.location.search);
    const savedUsers = params.get('users');
    if (savedUsers) setUsers(Number(savedUsers));
  }, []);

  useEffect(() => {
    // Sync changes to URL
    const params = new URLSearchParams(window.location.search);
    params.set('users', String(users));
    window.history.replaceState(
      {},
      '',
      `?${params.toString()}`
    );
  }, [users]);

  // ... rest of component
}

This is a small addition but critical for SaaS conversion funnels where users expect their choices to persist.

Why This Matters for SaaS

SaaS marketing sites aren't blogs. Every interactive element—calculator, comparison table, signup form—serves the conversion funnel. Standard static-site thinking (keep JavaScript to zero) leaves conversion tools neutered. Full React hydration (load everything) wastes bandwidth on users who bounce after 10 seconds.

Deferred islands are the middle path I've come to rely on. They're opinionated about when code loads, not whether it loads. For CitizenApp, this shifted the landing page from a glorified brochure to a functional sales tool that doesn't feel bloated.

Build it this way from day one. Your Lighthouse scores (and your sales team) will thank you.

WebSocket Real-Time Architecture: From Connection Pooling to Graceful Reconnection

Ugur Aslim — Sun, 12 Jul 2026 13:17:23 +0000

Real-time systems are seductive. You build a basic WebSocket connection, messages flow instantly, and it feels like magic. Then your first user's network hiccups, their browser crashes, or you deploy an update and suddenly 500 clients are screaming reconnect requests at your server. That's when you realize the Hello World examples glossed over the hard part.

I've built real-time collaboration features in CitizenApp, and I've learned that WebSocket architecture isn't about the connection itself—it's about what happens when the connection breaks. This post covers the patterns I actually use in production.

Why Connection Pooling Matters on the Server

Before we even talk about the client, let's address server capacity. Each WebSocket connection consumes memory and file descriptors. On my FastAPI backend, naive implementations spawn a new handler per connection and let garbage collection handle cleanup. That works until you hit 10k concurrent users and your CPU is thrashing.

I prefer explicit connection pooling with a bounded queue:

# FastAPI WebSocket Manager with pooling
from typing import Set
import asyncio
from fastapi import WebSocket

class ConnectionPool:
    def __init__(self, max_connections: int = 5000):
        self.active_connections: Set[WebSocket] = set()
        self.max_connections = max_connections
        self.lock = asyncio.Lock()

    async def connect(self, websocket: WebSocket):
        if len(self.active_connections) >= self.max_connections:
            await websocket.close(code=1008, reason="Server capacity exceeded")
            return False

        async with self.lock:
            self.active_connections.add(websocket)
            return True

    async def disconnect(self, websocket: WebSocket):
        async with self.lock:
            self.active_connections.discard(websocket)

    async def broadcast(self, message: dict, exclude: WebSocket = None):
        disconnected = set()
        for connection in self.active_connections:
            if exclude and connection == exclude:
                continue
            try:
                await connection.send_json(message)
            except:
                disconnected.add(connection)

        # Clean up dead connections
        for conn in disconnected:
            await self.disconnect(conn)

pool = ConnectionPool(max_connections=5000)

Why explicit pooling? Memory predictability. You know exactly how many connections you're holding. No surprise OOM kills at 3am.

The Heartbeat Pattern Prevents Zombie Connections

This one burned me hard. You think the connection is alive, but the client is offline or stuck. The server has no idea. Connections pile up consuming memory, and you're broadcasting to ghosts.

The heartbeat pattern (ping/pong) is your safety net:

// TypeScript Client with heartbeat
class ReliableWebSocket {
  private ws: WebSocket | null = null;
  private heartbeatInterval: number | null = null;
  private heartbeatTimeout: number | null = null;
  private messageQueue: any[] = [];
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;

  connect(url: string) {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(url);

      this.ws.onopen = () => {
        console.log("Connected");
        this.reconnectAttempts = 0;
        this.startHeartbeat();
        this.flushQueue();
        resolve(this.ws);
      };

      this.ws.onmessage = (event) => {
        const message = JSON.parse(event.data);

        // Server heartbeat response
        if (message.type === "pong") {
          clearTimeout(this.heartbeatTimeout!);
          return;
        }

        this.onMessage(message);
      };

      this.ws.onerror = reject;
    });
  }

  private startHeartbeat() {
    // Send ping every 30 seconds
    this.heartbeatInterval = window.setInterval(() => {
      if (this.ws?.readyState === WebSocket.OPEN) {
        this.ws.send(JSON.stringify({ type: "ping" }));

        // If we don't get pong within 5s, reconnect
        this.heartbeatTimeout = window.setTimeout(() => {
          console.warn("Heartbeat timeout, reconnecting...");
          this.reconnect();
        }, 5000);
      }
    }, 30000);
  }

  private async reconnect() {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      this.onError(new Error("Max reconnect attempts exceeded"));
      return;
    }

    this.reconnectAttempts++;
    const backoffMs = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);

    console.log(`Reconnecting in ${backoffMs}ms...`);
    await new Promise(r => setTimeout(r, backoffMs));

    try {
      await this.connect(this.url);
    } catch (error) {
      this.reconnect();
    }
  }

  private flushQueue() {
    while (this.messageQueue.length > 0) {
      const msg = this.messageQueue.shift();
      this.send(msg);
    }
  }

  send(message: any) {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(message));
    } else {
      this.messageQueue.push(message);
    }
  }

  private onMessage(message: any) {
    // Your app logic here
  }

  private onError(error: Error) {
    // Your error handling here
  }
}

And on the server:

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    await pool.connect(websocket)

    try:
        while True:
            data = await asyncio.wait_for(websocket.receive_text(), timeout=60.0)
            message = json.loads(data)

            if message.get("type") == "ping":
                await websocket.send_json({"type": "pong"})
            else:
                await pool.broadcast(message)

    except asyncio.TimeoutError:
        await websocket.close(code=1000, reason="Heartbeat timeout")
    except Exception as e:
        print(f"Error: {e}")
    finally:
        await pool.disconnect(websocket)

Why? Heartbeats detect dead connections before they cause problems. No ghosts.

Graceful Reconnection with Exponential Backoff

Exponential backoff is non-negotiable. Hammering the server with reconnect requests during an outage creates a DoS attack on yourself.

Notice the Math.pow(2, this.reconnectAttempts) logic above. First attempt: 2s. Second: 4s. Third: 8s. Max out at 30s. This gives the network time to heal without overwhelming your server.

Message Queue During Disconnection

Users expect their messages sent even if briefly offline. The queue pattern above buffers messages and flushes when reconnected:

send(message: any) {
  if (this.ws?.readyState === WebSocket.OPEN) {
    this.ws.send(JSON.stringify(message));
  } else {
    // Queue for later
    this.messageQueue.push(message);
  }
}

Simple but critical. Without this, users see "sending..." spinners that never resolve.

Gotcha: Message Ordering During Reconnection

Here's what bit me: if the client reconnects while messages are still in flight, you can violate ordering guarantees. User A sends "create item", gets disconnected, then reconnects and sends "update item"—but the server's heartbeat timeout might have already processed the first message on a background task.

I solved this with idempotent message IDs:

private messageId = 0;

send(message: any) {
  message.id = ++this.messageId;
  message.timestamp = Date.now();

  if (this.ws?.readyState === WebSocket.OPEN) {
    this.ws.send(JSON.stringify(message));
  } else {
    this.messageQueue.push(message);
  }
}

On the server, deduplicate:

seen_ids = set()

if message.get("id") in seen_ids:
    return  # Already processed

seen_ids.add(message.get("id"))
# Process message

This is boring infrastructure, but it's what separates "cool demo" from "production SaaS." Real-time systems fail constantly—your job is making those failures invisible to users.

Building Multi-Tenant SaaS Databases: Isolation, Performance, and PostgreSQL Strategies

Ugur Aslim — Sat, 11 Jul 2026 08:08:33 +0000

Building Multi-Tenant SaaS Databases: Isolation, Performance, and PostgreSQL Strategies

I've burned myself on multi-tenancy decisions twice—once choosing wrong at the start, once changing my mind halfway through CitizenApp. Both were expensive. The database architecture you pick shapes your API contracts, your security model, and eventually your scaling ceiling. Get it wrong and you'll either leak data between customers or run out of database connections at 50 customers.

There are three main approaches: shared database with row-level security (RLS), separate schemas per tenant, or separate databases entirely. I'll explain why I settled on shared database + RLS + application-level tenant context for CitizenApp, and when you'd choose differently.

Why Most Teams Choose Wrong Initially

The appeal of "one database, one schema, multiple customers" is obvious: simple deployment, easy backups, cheap. But RLS is misunderstood. People think "just add a WHERE clause" solves multi-tenancy. It doesn't.

The real cost isn't implementation—it's cognitive overhead and the blast radius when you mess up. One misconfigured policy, one rogue query without tenant context, and you've silently leaked customer data. I prefer explicit isolation at the application layer with RLS as a failsafe, not the primary mechanism.

The Shared Database + RLS Approach (What I Use Now)

Here's the mental model: your application is responsible for tenant context. PostgreSQL's RLS is the safety net.

-- Schema setup
CREATE TABLE tenants (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    email TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(tenant_id, email)
);

CREATE TABLE workspaces (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    name TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Enable RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE workspaces ENABLE ROW LEVEL SECURITY;

-- The critical policy: tenant context via JWT
CREATE POLICY tenant_isolation ON users
    USING (tenant_id = current_setting('app.tenant_id')::UUID);

CREATE POLICY tenant_isolation ON workspaces
    USING (tenant_id = current_setting('app.tenant_id')::UUID);

The current_setting('app.tenant_id') is your tenant context. You set it per request in your application:

// FastAPI middleware (Python)
from fastapi import Request, HTTPException
from sqlalchemy import text
import jwt

@app.middleware("http")
async def set_tenant_context(request: Request, call_next):
    # Extract tenant from JWT
    auth_header = request.headers.get("Authorization")
    if not auth_header:
        raise HTTPException(status_code=401)

    token = auth_header.split(" ")[1]
    payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    tenant_id = payload.get("tenant_id")

    if not tenant_id:
        raise HTTPException(status_code=403, detail="No tenant in token")

    # Set PostgreSQL context variable
    async with db.begin() as conn:
        await conn.execute(
            text("SET app.tenant_id = :tenant_id"),
            {"tenant_id": str(tenant_id)}
        )

    response = await call_next(request)
    return response

Now any query automatically filters by tenant:

# SQLAlchemy query
from sqlalchemy import select

stmt = select(User).where(User.email == "test@example.com")
# RLS automatically adds: AND tenant_id = current_setting('app.tenant_id')::UUID
result = await db.execute(stmt)

Why this works: Your application controls the JWT payload, so you control which tenant context gets set. If a developer forgets to pass the token, RLS blocks the query. If someone SQL-injects a tenant_id, the RLS policy still enforces isolation.

Schema-Per-Tenant When You Need It

I wouldn't use this for CitizenApp at 9 features. But for highly regulated customers (healthcare, finance) who demand complete isolation, it's worth it:

-- Dynamic schema creation
CREATE SCHEMA AUTHORIZATION tenant_${tenant_id};

-- Tenant-specific tables
CREATE TABLE tenant_${tenant_id}.users (
    id UUID PRIMARY KEY,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);

Trade-offs: You get bulletproof isolation. Backups are simpler (one schema = one customer's data). But now you're managing schema migrations across N schemas. Connection pooling gets weird. Your queries need dynamic schema prefixing. I'd only pick this if:

You have <50 tenants and they're high-value
Data residency laws demand it (GDPR, data sovereignty)
Your customers audit their own databases

For everyone else, it's overkill that creates operational friction.

Performance Doesn't Care About Tenancy (Usually)

Here's what surprised me: the bottleneck isn't tenant isolation, it's working set size. If your shared database has 100GB of data across 1,000 tenants, queries are slower than if you had 100MB per tenant in separate databases.

This matters for analytics queries. If a tenant runs a "sum all invoices" query, it'll scan fewer rows with schema separation. But for transactional queries (OLTP), modern PostgreSQL with proper indexes doesn't care if you have 1 tenant or 1,000 in the same table.

-- Proper indexing makes RLS queries fast
CREATE INDEX idx_workspaces_tenant_id ON workspaces(tenant_id);
CREATE INDEX idx_workspaces_tenant_created ON workspaces(tenant_id, created_at DESC);

-- Query planner will use tenant_id index first

I monitor this in CitizenApp. Tenant isolation adds <1ms to query time with proper indexes.

Gotcha: RLS Doesn't Work With Prepared Statements Everywhere

This one burned me. Some PostgreSQL drivers cache prepared statements before the tenant context is set:

// DANGEROUS - prepared statement might be cached without context
const query = db.prepare("SELECT * FROM users WHERE id = $1");
query.run(userId); // Might not have tenant_id context!

I solved it by disabling statement caching for sensitive queries:

# SQLAlchemy - don't cache sensitive queries
from sqlalchemy import text

stmt = text("SELECT * FROM users WHERE id = :id").execution_options(
    compiled_cache=None
)
result = await db.execute(stmt, {"id": user_id})

Or use ORM queries, which don't suffer from this:

# SQLAlchemy ORM - RLS applies consistently
user = await db.get(User, user_id)

The Real Decision: What's Your Risk?

Use shared database + RLS if:

You have <10,000 tenants
Data leakage is recoverable (you'll catch it in logs)
You want deployment simplicity

Use schema-per-tenant if:

You have <100 high-value tenants
Data leakage is a regulatory violation
Your customers demand audit trails per schema

Use separate databases if:

You're a platform (Stripe, Vercel) with thousands of autonomous customers
You need per-tenant backups and recovery
You accept operational complexity as the cost of isolation

I chose shared database + RLS because CitizenApp's security model relies on application authentication anyway. Adding schema separation would've delayed launch and created deployment headaches I didn't need. But if I'd been building a regulated product, I'd schema-separate from day one.

Pick the simplest approach that your risk tolerance allows. You can always migrate later (I did).

Task Queues in Production: Celery vs Temporal vs Native FastAPI

Ugur Aslim — Thu, 09 Jul 2026 10:41:54 +0000

Task Queues in Production: Celery vs Temporal vs Native FastAPI

I've shipped async job handling in CitizenApp three different ways. Each one taught me something painful. Here's what actually matters when you're running a SaaS at scale.

The problem is simple: some work shouldn't block HTTP responses. Sending emails, processing PDFs, syncing external APIs, generating reports—these take seconds or minutes. Jamming them into request handlers tanks user experience. Task queues solve this. The question isn't if you need one; it's which architecture loses you least sleep.

Native FastAPI + asyncio: The Trap

Let's start with the tempting route.

from fastapi import FastAPI
import asyncio

app = FastAPI()

async def send_onboarding_email(user_id: int):
    await asyncio.sleep(2)  # Simulate email service
    print(f"Email sent to user {user_id}")

@app.post("/register")
async def register(email: str):
    # Fire and forget
    asyncio.create_task(send_onboarding_email(user_id=123))
    return {"status": "registered"}

This feels great for 3 months. It costs nothing extra. No infrastructure. No Redis. No broker.

Then you deploy. A task crashes. You don't know it failed—the exception dies silently in a background coroutine. Your users never get their onboarding emails. You discover this when churn spikes.

Or your deployment process kills the worker mid-task. That 30-minute PDF generation? Gone. No retry. No queue persistence.

I prefer task queues for anything that matters because loose tasks are invisible failures waiting to happen.

The hidden cost of native async is observability debt. You're building error tracking yourself. You're manually implementing retries. You're debugging timeouts with no context.

For fire-and-forget analytics pings? Sure, use create_task(). For anything touching business logic, user data, or money? No. You need a queue.

Celery: The Industry Standard With Operational Friction

Celery is the default for Django/Python SaaS. It's battle-tested. It handles retries, scheduling, dead-letter queues, and monitoring out of the box.

Here's CitizenApp's email task:

from celery import Celery, Task
from celery.exceptions import MaxRetriesExceededError
import smtplib

celery = Celery('citizenapplications')
celery.conf.update(
    broker_url='redis://localhost:6379/0',
    result_backend='redis://localhost:6379/1',
    task_serializer='json',
    accept_content=['json'],
    timezone='UTC',
    enable_utc=True,
)

@celery.task(bind=True, max_retries=5)
def send_onboarding_email(self, user_id: int, email: str):
    try:
        # Your email logic
        result = smtplib.send_email(email)
        return {"status": "sent", "user_id": user_id}
    except smtplib.SMTPException as exc:
        # Exponential backoff: 2^retry_count minutes
        retry_delay = (2 ** self.request.retries) * 60
        raise self.retry(exc=exc, countdown=retry_delay)
    except Exception as exc:
        self.update_state(state='FAILURE', meta=str(exc))
        raise

# In FastAPI
@app.post("/register")
async def register(email: str):
    send_onboarding_email.delay(user_id=123, email=email)
    return {"status": "registered"}

This is solid. Tasks are logged. Failed tasks sit in Redis with retry metadata. You can inspect the queue with celery inspect active. You can manually requeue dead tasks.

The gotcha: Celery's operational overhead grows with your queue size.

At CitizenApp, we hit 200K daily tasks. Our Celery workers (running on Render) started eating CPU during traffic spikes. We had to tune worker concurrency, prefetch settings, and beat scheduler settings. Most engineers don't realize Celery is also a distributed system—it has network partitions, clock skew issues, and can lose tasks if Redis dies before tasks commit to disk.

Celery shines for:

Scheduled jobs (reports, cleanups, syncs)
High-volume async work with retry logic
Teams comfortable debugging distributed systems

Celery fails when:

You need guaranteed execution ordering (Celery's guarantees are best-effort)
You want tight observability without external tools (Datadog + Celery is better, but that's extra cost)
Task dependencies matter (task A must finish before B; Celery makes this messy)

Temporal: The Workflow Engine

This is the newer entrant. Temporal treats your entire job as a durable workflow. It persists state, handles retries, and guarantees execution semantics.

from temporalio import workflow, activity
from datetime import timedelta

@activity.defn
async def send_email_activity(email: str) -> str:
    # Even if this activity fails mid-execution,
    # Temporal replays it deterministically
    await send_email_service(email)
    return f"Email sent to {email}"

@activity.defn
async def create_onboarding_checklist(user_id: int) -> dict:
    return {"checklist": [...]}

@workflow.defn
class OnboardingWorkflow:
    @workflow.run
    async def run(self, user_id: int, email: str):
        # Temporal guarantees this sequence happens exactly once
        await workflow.execute_activity(
            send_email_activity,
            email,
            start_to_close_timeout=timedelta(minutes=5)
        )
        await workflow.execute_activity(
            create_onboarding_checklist,
            user_id,
            start_to_close_timeout=timedelta(minutes=10)
        )
        return {"status": "onboarding_complete"}

Temporal's genius: if a worker crashes, it replays the workflow from the event log. Activities are idempotent by design. You get causality—tasks have dependencies that are enforced, not coded around.

The cost: operational complexity and Temporal Cloud pricing ($25/million events).

For CitizenApp's volume, that's roughly $150–200/month. You also need to run a Temporal server (or use Cloud). Local development requires spinning up containers.

Temporal wins for:

Workflows with multi-step dependencies
Systems where order and atomicity matter (payment processing, provisioning)
Teams that can invest in understanding distributed workflows

Temporal loses when:

You have simple, independent tasks
Your operations team isn't comfortable with event sourcing concepts
You're optimizing for "cheapest possible first SaaS"

What I Actually Run

At CitizenApp:

Celery for high-volume async (emails, webhooks, file processing)
Native asyncio tasks for non-critical analytics only
Temporal for user provisioning workflows (where ordering is critical)

This hybrid approach lets us keep costs reasonable while guaranteeing reliability where it matters.

The Real Question

Before picking a queue, ask yourself:

Can this task fail silently? (No → you need a queue)
Does failure order matter? (Yes → Temporal, maybe Celery with careful orchestration)
What's your monthly task volume? (10K → Celery; 1M+ → consider Temporal; <1K → native async)
Do you have Redis/infra ops? (No → Temporal Cloud; Yes → Celery on EC2/Render)

What I missed: I initially thought Celery was overkill for CitizenApp. Two months later, a single worker crash lost 400 unconfirmed signups because tasks evaporated. That's the real cost of cheap solutions.

Task queues aren't glamorous, but they're the difference between a SaaS that silently eats data and one your customers trust.

Authentication in Modern SaaS: Passwordless & Multi-Tenant Patterns

Ugur Aslim — Wed, 08 Jul 2026 09:32:06 +0000

I've watched too many SaaS founders bolt on authentication as an afterthought and regret it within 6 months. By then, they're shipping feature work while wrestling with token expiration bugs, multi-tenant data leaks, and angry customers locked out at 2 AM. I built CitizenApp on a different principle: authentication is infrastructure, not scaffolding. And passwordless + AI-driven verification is the path to sane, scalable auth that actually serves your users instead of becoming your primary support burden.

Why Passwordless Isn't Just Hype

Passwords are a liability you don't need. That's not idealism—it's math. Every password you store is a vector; every rotation cycle is operational overhead. But passwordless adoption fails when it's treated as a UX gimmick ("click the magic link!") instead of a security architecture.

I prefer passwordless-first because:

Eliminates password fatigue — Your users stop managing yet another credential. They use their email or phone they already check obsessively.
Reduces your attack surface — No bcrypt leaks, no replay vulnerabilities, no password reset token circulation.
Scales auth complexity gracefully — When you add multi-tenancy, passwordless becomes a force multiplier for session isolation.

The catch: passwordless only works if you nail the verification layer. That's where most implementations fail. They generate a token, email a link, and call it done. But in a multi-tenant SaaS, you need context-aware verification—knowing not just that someone verified their email, but which tenant they're logging into and whether they have permission.

The Multi-Tenant Verification Problem

Here's what I missed the first time: naive passwordless implementations create a single verification flow that doesn't account for tenant context. User clicks the link, gets verified, and then you have to figure out which workspace they belong to. That's a race condition waiting to happen.

The pattern I now use embeds tenant context into the verification token itself:

// FastAPI backend — generating a passwordless token with tenant context
from fastapi import FastAPI, HTTPException
from sqlalchemy import select
from datetime import datetime, timedelta
import jwt
import anthropic

app = FastAPI()

async def generate_passwordless_token(
    email: str,
    tenant_id: str,
    secret_key: str
) -> str:
    """
    Generate a JWT that encodes both identity and tenant context.
    This prevents cross-tenant verification hijacking.
    """
    payload = {
        "sub": email,
        "tenant_id": tenant_id,
        "type": "passwordless_verify",
        "iat": datetime.utcnow(),
        "exp": datetime.utcnow() + timedelta(minutes=15),
    }
    token = jwt.encode(payload, secret_key, algorithm="HS256")
    return token

async def send_passwordless_email_with_claude(
    email: str,
    tenant_id: str,
    tenant_name: str,
    verification_url: str,
):
    """
    Use Claude to generate contextual, personalized login emails.
    This sounds fancy but solves a real problem: generic emails get flagged as phishing.
    """
    client = anthropic.Anthropic()

    prompt = f"""Generate a professional passwordless login email for a SaaS application.

Email: {email}
Workspace: {tenant_name}
Login link: {verification_url}

Requirements:
- Be concise (2-3 sentences max)
- Mention the workspace name to confirm they're logging into the right place
- Include clear CTA text
- Warn that the link expires in 15 minutes
- Professional but friendly tone

Return ONLY the email body, no subject line."""

    message = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=300,
        messages=[
            {"role": "user", "content": prompt}
        ]
    )

    email_body = message.content[0].text
    # Send via your email provider (Resend, SendGrid, etc.)
    print(f"Email body:\n{email_body}")
    return email_body

Why use Claude here? Because phishing filters treat templated emails like spammers. A slightly varied, context-aware email body improves deliverability and confirms to the user they're logging into the right workspace. It's a win on security theater that's actually theater worth watching.

Session Isolation & RBAC Layer

Once someone verifies, you need bulletproof session isolation. This is where I've seen the most damage: a token issued for one tenant accidentally grants access to another's data.

// React 19 component with multi-tenant context isolation
import { useEffect, useState } from 'react';
import { useAuth } from '@/context/AuthContext';

interface AuthSession {
  access_token: string;
  tenant_id: string;
  role: 'admin' | 'member' | 'viewer';
  expires_at: number;
}

export function LoginPage({ defaultTenantId }: { defaultTenantId?: string }) {
  const [email, setEmail] = useState('');
  const [loading, setLoading] = useState(false);
  const [step, setStep] = useState<'email' | 'verify'>('email');
  const { setSession } = useAuth();

  const handleEmailSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      const response = await fetch('/api/auth/passwordless/request', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          email,
          tenant_id: defaultTenantId,
        }),
      });

      if (!response.ok) throw new Error('Failed to send verification email');
      setStep('verify');
    } catch (error) {
      console.error(error);
    } finally {
      setLoading(false);
    }
  };

  const handleVerificationToken = async (token: string) => {
    try {
      const response = await fetch('/api/auth/passwordless/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token }),
      });

      if (!response.ok) throw new Error('Verification failed');

      const session: AuthSession = await response.json();

      // Store session WITH tenant isolation
      // Critical: tenant_id is part of the session, not derived from URL
      setSession(session);

      // Redirect to tenant-specific dashboard
      window.location.href = `/workspace/${session.tenant_id}/dashboard`;
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <div className="flex items-center justify-center min-h-screen bg-gray-900">
      {step === 'email' ? (
        <form onSubmit={handleEmailSubmit} className="w-96 space-y-4">
          <input
            type="email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            placeholder="you@company.com"
            className="w-full px-4 py-2 bg-gray-800 border border-gray-700 rounded text-white"
            required
          />
          <button
            type="submit"
            disabled={loading}
            className="w-full px-4 py-2 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white font-medium rounded"
          >
            {loading ? 'Sending...' : 'Send Login Link'}
          </button>
        </form>
      ) : (
        <div className="text-center space-y-2">
          <p className="text-gray-300">Check your email for a login link</p>
          <p className="text-gray-500 text-sm">Link expires in 15 minutes</p>
        </div>
      )}
    </div>
  );
}

On the backend, validate that the token's tenant_id matches the request context:


python
# FastAPI — verify token and enforce tenant isolation
from fastapi import Depends, HTTPException, status

async def verify_passwordless_token(
    token: str,
    expected_tenant_id: str,
    secret_key: str,
) -> dict:
    """
    Decode and validate passwordless token.
    CRITICAL: Verify tenant_id matches expected value to prevent cross-tenant access.
    """
    try:
        payload = jwt.decode(token, secret_key, algorithms=["HS256"])
    except jwt.ExpiredSignatureError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Token expired"
        )
    except jwt.InvalidTokenError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token"
        )

    # GOTCHA: This is where multi-tenant bugs live
    if payload.get("tenant_id") != expected_tenant_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Token not valid for this workspace"
        )

    if payload.get("type") != "passwordless_verify":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token type"
        )

    return payload

@app.post("/api/auth/passwordless/verify")
async def verify_login(request: PasswordlessVerifyRequest, db: AsyncSession = Depends(get_db)):
    payload = await verify_passwordless_token(
        token=request.token,
        expected_tenant_id=request.tenant_id,
        secret_key=settings.SECRET_KEY,
    )

    email = payload["sub"]
    user = await db.execute(
        select(User).where(User.email == email)
    )
    user = user.scalar_one_or_none()

    if not user:
        raise HTTPException(status_code=404, detail="User not found")

    # Create session token

Authentication in Modern Full-Stack Apps: JWT, Sessions, and OAuth 2.0

Ugur Aslim — Mon, 06 Jul 2026 07:53:05 +0000

I've implemented authentication in CitizenApp across multiple iterations, and I'm going to be blunt: most tutorials get this wrong. They'll show you a basic JWT implementation or a simple session setup, but they won't show you the real production patterns that keep your application secure without shooting yourself in the foot six months later.

Let me walk you through what actually works at scale, starting with the core decision that shapes everything else.

JWT vs Sessions: The Actual Trade-offs

Everyone treats this like a binary choice, but it's not. Here's what I learned the hard way:

JWT is stateless, which is its greatest strength and weakness. The appeal is obvious—no server-side session store, scales horizontally without coordination, works beautifully for distributed systems. But statelessness means you can't revoke a token until it expires. This burned me when a user in CitizenApp got compromised and I couldn't immediately invalidate their access. They had to wait 15 minutes for their token to expire.

Sessions are stateful but revocable. If someone gets hacked, you revoke the session immediately. The trade-off is you need a persistent store (Redis, database) and you're hitting it on every request to verify the session exists. At scale, this is fine—Redis is fast—but it's architectural overhead.

I prefer hybrid authentication: JWT for the access token (short-lived, 15 minutes), and a session-like refresh token stored server-side that's long-lived (7 days). This gives you revocation capability while keeping the horizontal scalability of JWTs.

Here's why: an attacker with a stolen short-lived JWT can't do much damage. A stolen refresh token? That's bad, but you can revoke it immediately. And you get the best of both worlds.

The FastAPI Implementation

Let me show you the actual pattern I use in CitizenApp. First, the token schemas:

from datetime import datetime, timedelta
from typing import Optional
from pydantic import BaseModel

class TokenResponse(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"

class TokenPayload(BaseModel):
    sub: int  # user_id
    exp: datetime
    iat: datetime
    type: str  # "access" or "refresh"

Now the crucial part—generating both tokens with different expiration times:

from jose import JWTError, jwt
import os

SECRET_KEY = os.getenv("SECRET_KEY")
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 15
REFRESH_TOKEN_EXPIRE_DAYS = 7

def create_access_token(user_id: int) -> str:
    now = datetime.utcnow()
    expires = now + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    payload = {
        "sub": user_id,
        "type": "access",
        "iat": now.isoformat(),
        "exp": expires.isoformat(),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def create_refresh_token(user_id: int) -> str:
    now = datetime.utcnow()
    expires = now + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
    payload = {
        "sub": user_id,
        "type": "refresh",
        "iat": now.isoformat(),
        "exp": expires.isoformat(),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

The refresh token gets stored server-side. I use a simple RefreshToken table:

from sqlalchemy import Column, Integer, String, DateTime, Boolean
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class RefreshTokenModel(Base):
    __tablename__ = "refresh_tokens"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    token_hash = Column(String(255), unique=True, nullable=False)  # hashed JWT
    expires_at = Column(DateTime, nullable=False)
    is_revoked = Column(Boolean, default=False)
    created_at = Column(DateTime, default=datetime.utcnow)

Why store it hashed? If your database gets compromised, tokens aren't immediately usable. Use SHA-256:

import hashlib

def hash_token(token: str) -> str:
    return hashlib.sha256(token.encode()).hexdigest()

async def store_refresh_token(db: Session, user_id: int, token: str):
    token_hash = hash_token(token)
    expires_at = datetime.utcnow() + timedelta(days=7)

    db_token = RefreshTokenModel(
        user_id=user_id,
        token_hash=token_hash,
        expires_at=expires_at
    )
    db.add(db_token)
    db.commit()

React 19 Implementation with Secure Storage

On the frontend, here's where most implementations fail: they store tokens in localStorage, which is vulnerable to XSS. I store the access token in memory, and the refresh token in an httpOnly cookie (set by FastAPI during login).

// hooks/useAuth.ts
import { useState, useCallback } from 'react';

interface AuthState {
  user: User | null;
  accessToken: string | null;
  isLoading: boolean;
}

export function useAuth() {
  const [authState, setAuthState] = useState<AuthState>({
    user: null,
    accessToken: null,
    isLoading: false,
  });

  const login = useCallback(async (email: string, password: string) => {
    setAuthState(prev => ({ ...prev, isLoading: true }));

    try {
      const response = await fetch('/api/auth/login', {
        method: 'POST',
        credentials: 'include', // Send cookies
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
      });

      if (!response.ok) throw new Error('Login failed');

      const data = await response.json();
      setAuthState({
        user: data.user,
        accessToken: data.access_token,
        isLoading: false,
      });
    } catch (error) {
      setAuthState(prev => ({ ...prev, isLoading: false }));
      throw error;
    }
  }, []);

  return { ...authState, login };
}

The FastAPI login endpoint sets the refresh token as an httpOnly cookie:

from fastapi import Response

@router.post("/auth/login")
async def login(credentials: LoginSchema, response: Response, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.email == credentials.email).first()

    if not user or not verify_password(credentials.password, user.password_hash):
        raise HTTPException(status_code=401, detail="Invalid credentials")

    access_token = create_access_token(user.id)
    refresh_token = create_refresh_token(user.id)

    await store_refresh_token(db, user.id, refresh_token)

    # httpOnly, Secure, SameSite—the holy trinity
    response.set_cookie(
        key="refresh_token",
        value=refresh_token,
        httponly=True,
        secure=True,  # HTTPS only
        samesite="strict",
        max_age=7 * 24 * 60 * 60,
    )

    return {
        "user": user.dict(),
        "access_token": access_token,
        "token_type": "bearer",
    }

Refresh Token Rotation

The real security magic happens when your access token expires. You call the refresh endpoint:

@router.post("/auth/refresh")
async def refresh(request: Request, db: Session = Depends(get_db)):
    refresh_token = request.cookies.get("refresh_token")

    if not refresh_token:
        raise HTTPException(status_code=401, detail="No refresh token")

    try:
        payload = jwt.decode(refresh_token, SECRET_KEY, algorithms=[ALGORITHM])
        user_id = payload["sub"]
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

    # Check if token exists and isn't revoked
    token_hash = hash_token(refresh_token)
    db_token = db.query(RefreshTokenModel).filter(
        RefreshTokenModel.token_hash == token_hash,
        RefreshTokenModel.is_revoked == False,
    ).first()

    if not db_token:
        raise HTTPException(status_code=401, detail="Token revoked or expired")

    # Issue new access token AND rotate refresh token
    new_access_token = create_access_token(user_id)
    new_refresh_token = create_refresh_token(user_id)

    # Revoke old refresh token
    db_token.is_revoked = True
    db.commit()

    # Store new one
    await store_refresh_token(db, user_id, new_refresh_token)

    response = JSONResponse({"access_token": new_access_token})
    response.set_cookie(
        key="refresh_token",
        value=new_refresh_token,
        httponly=True,
        secure=True,
        samesite="strict",
        max_age=7 * 24 * 60 * 60,
    )
    return response

Gotcha: CSRF When Using Cookies

Here's what burned me: if you're storing the refresh token in cookies, you're vulnerable to CSRF attacks unless you implement CSRF protection. React doesn't automatically add CSRF tokens—you have to do it yourself.

When you make state-changing requests (POST, PUT, DELETE), extract the CSRF token from a meta tag or cookie and send it:


typescript
// Middleware to add CSRF token

React 19 useCallback Dependencies in Multi-Tenant Dashboards: Why Your AI Feature Memoization Is Causing Stale Closures

Ugur Aslim — Sun, 05 Jul 2026 16:54:15 +0000

React 19 useCallback Dependencies in Multi-Tenant Dashboards: Why Your AI Feature Memoization Is Causing Stale Closures

I've shipped CitizenApp to production with 9 concurrent AI features across 200+ tenant accounts. Last month, I spent 6 hours debugging why Tenant B's Claude API calls were occasionally using Tenant A's system prompts. The root cause? A useCallback dependency list that worked fine in my single-tenant prototype but became a data-leaking landmine once multi-tenant context entered the picture.

This is the invisible bug that doesn't show up in staging. It only surfaces under specific conditions: rapid tenant switches, slow network responses, or concurrent feature toggles. Your error logs stay clean. Your TypeScript types pass. But somewhere, a stale closure is capturing yesterday's tenant ID.

The Single-Tenant Illusion

React 19's useCallback memoization makes sense in isolation. You wrap an expensive handler to prevent child re-renders. This works beautifully when you have one user and one data context.

const TenantDashboard = () => {
  const { tenantId } = useContext(TenantContext);
  const [features, setFeatures] = useState([]);

  // This looks safe
  const handleAnalyzeData = useCallback(async (data: unknown[]) => {
    const response = await fetch(`/api/analyze?tenant=${tenantId}`, {
      method: 'POST',
      body: JSON.stringify(data),
    });
    return response.json();
  }, [tenantId]);

  return <FeatureGrid onAnalyze={handleAnalyzeData} features={features} />;
};

In a single-tenant app, this works. tenantId changes rarely. The dependency array catches it. Developers everywhere praise memoization for preventing wasteful re-renders.

Then you add multi-tenancy.

Where It Falls Apart

The problem emerges when:

User switches tenants (common in admin dashboards or managed accounts)
AI feature request is in-flight when the switch happens
Child component still holds the old memoized callback
Request completes, but context has changed

Here's the scenario that burned me:

// Parent component
const MultiTenantApp = () => {
  const [activeTenant, setActiveTenant] = useState<string>('tenant-a');

  return (
    <TenantContext.Provider value={{ tenantId: activeTenant }}>
      <DashboardWithFeatures />
      <TenantSwitcher onSwitch={setActiveTenant} />
    </TenantContext.Provider>
  );
};

// Child that memoizes
const DashboardWithFeatures = () => {
  const { tenantId } = useContext(TenantContext);

  const callClaudeAPI = useCallback(
    async (prompt: string) => {
      // This closure captures tenantId at callback creation time
      const result = await anthropic.messages.create({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 1024,
        system: `You are analyzing data for tenant: ${tenantId}`, // STALE!
        messages: [{ role: 'user', content: prompt }],
      });
      return result;
    },
    [tenantId] // Dependency is correct, but timing matters
  );

  return <FeaturePanel onCallClaude={callClaudeAPI} />;
};

// Grandchild that calls the memoized function
const FeaturePanel = ({ onCallClaude }: { onCallClaude: (p: string) => Promise<void> }) => {
  const handleClick = async () => {
    // User clicks button while tenant is 'tenant-a'
    await onCallClaude('Summarize this data');
    // By the time this completes, context switched to 'tenant-b'
    // But onCallClaude still has 'tenant-a' in its closure!
  };

  return <button onClick={handleClick}>Analyze with Claude</button>;
};

The callback dependency list includes tenantId, so React should recreate it when tenantId changes. And it does. But there's a timing issue: if the async request started under Tenant A and completes after switching to Tenant B, the request in-flight used Tenant A's system prompt.

This isn't just an annoyance—it's a data isolation violation in a SaaS context.

The Real Problem: Async Boundaries

The dependency array prevents stale memoization at render time. But it doesn't protect against closures captured during async operations.

const callClaudeAPI = useCallback(
  async (prompt: string) => {
    // At THIS moment, tenantId is correct
    const systemPrompt = `You are analyzing data for tenant: ${tenantId}`;

    // But here we suspend—what if tenantId changes while awaiting?
    const result = await anthropic.messages.create({
      model: 'claude-3-5-sonnet-20241022',
      max_tokens: 1024,
      system: systemPrompt,
      messages: [{ role: 'user', content: prompt }],
    });

    // The closure still holds the tenantId from line 1
    // If user switched tenants, this is now stale
    return result;
  },
  [tenantId]
);

React can't know that your closure captured tenantId at the top of the async function. It only knows the dependency changed at render time—but by then, the async operation is already mid-flight.

The Solution: Defer Context Reading to Call Time

Stop capturing context values in the closure. Instead, read them when the callback executes.

const DashboardWithFeatures = () => {
  const tenantContextRef = useRef<string>('');
  const { tenantId } = useContext(TenantContext);

  // Update ref whenever context changes—this is cheap
  useEffect(() => {
    tenantContextRef.current = tenantId;
  }, [tenantId]);

  const callClaudeAPI = useCallback(
    async (prompt: string) => {
      // Read the CURRENT tenantId from ref, not the closure
      const currentTenantId = tenantContextRef.current;

      const result = await anthropic.messages.create({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 1024,
        system: `You are analyzing data for tenant: ${currentTenantId}`,
        messages: [{ role: 'user', content: prompt }],
      });
      return result;
    },
    [] // Empty dependency array—callback never changes
  );

  return <FeaturePanel onCallClaude={callClaudeAPI} />;
};

Now the callback is truly stable, but it reads tenantId from a ref that updates independently. When the async request completes, it uses the current tenant, not the captured one.

Why this matters: In CitizenApp, I have 9 AI features running concurrently. Each one was creating new callback instances on every tenant switch. The ref pattern reduced callback recreation by ~85% while actually improving safety.

Better: Custom Hook for Tenant-Safe Callbacks

This pattern happens repeatedly, so I extracted it:

// hooks/useTenantCallback.ts
export const useTenantCallback = <T extends (...args: unknown[]) => unknown>(
  callback: (tenantId: string, ...args: Parameters<T>) => ReturnType<T>
): ((...args: Parameters<T>) => ReturnType<T>) => {
  const { tenantId } = useContext(TenantContext);
  const tenantRef = useRef(tenantId);

  useEffect(() => {
    tenantRef.current = tenantId;
  }, [tenantId]);

  return useCallback(
    (...args: Parameters<T>) => callback(tenantRef.current, ...args),
    []
  );
};

// Usage
const DashboardWithFeatures = () => {
  const callClaudeAPI = useTenantCallback(
    async (tenantId: string, prompt: string) => {
      return anthropic.messages.create({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 1024,
        system: `Tenant: ${tenantId}`,
        messages: [{ role: 'user', content: prompt }],
      });
    }
  );

  return <FeaturePanel onCallClaude={callClaudeAPI} />;
};

This hook ensures your tenant context is always fresh, callbacks are always stable, and you can't accidentally capture stale context.

Gotcha: Ref Updates Aren't Synchronous

I initially tried to use useContext directly inside the callback:

const callClaudeAPI = useCallback(async (prompt: string) => {
  const { tenantId } = useContext(TenantContext); // DON'T DO THIS
  // ...
}, []);

This breaks. You can't call hooks inside callbacks. The ref pattern exists because refs update synchronously while component renders don't.

What I Missed

I thought React 19's improved dependency tracking would catch this. It doesn't. The dependency array is a compile-time safety tool, not a runtime guarantee against async stale closures. In a multi-tenant SaaS, every callback that references tenant-specific data needs this pattern.

For CitizenApp, this bug would have meant Claude API calls occasionally using wrong system prompts, potentially leaking context between tenants. It was invisible until I added rapid tenant-switching to my testing suite.

Use the ref pattern. Extract it to a custom hook. Test with rapid context changes.