DEV Community: Ugur Aslim

React 19 Compound Components with Tailwind CSS: Building Flexible Multi-Feature AI Dashboards Without Wrapper Div Sprawl

Ugur Aslim — Wed, 10 Jun 2026 07:41:40 +0000

React 19 Compound Components with Tailwind CSS: Building Flexible Multi-Feature AI Dashboards Without Wrapper Div Sprawl

I'm going to be direct: compound components are the most underrated pattern in modern React, and React 19 makes them so clean that ignoring them is a mistake. I learned this the hard way while rebuilding CitizenApp's dashboard—we had 9 AI features, each needing different card layouts, and I kept reaching for prop drilling hell until I realized the pattern I needed was right in front of me.

Here's the problem: when you're building a multi-tenant SaaS dashboard with heterogeneous AI widgets, you end up with cards that need different internal structures. One widget needs a two-column grid inside the card body. Another needs custom spacing. A third needs the footer to collapse on mobile. You either:

Create a Card component with 47 props (headerClassName, bodyPadding, footerBg, etc.)
Use CSS-in-JS to dynamically generate class names
Accept wrapper divs and prop drilling nightmare

I prefer compound components because they let each part of the card be independently styled while sharing minimal internal state. This is the React 19 way.

Why Compound Components Win for Dashboards

The compound component pattern treats a component family (Card, CardHeader, CardBody, CardFooter) as a cohesive unit that manages shared state internally via context, but delegates all styling to the consumer. This is powerful for dashboards because:

Flexibility without explosion: Each dashboard can compose cards however it needs without creating new component variants
No prop drilling: Child components access what they need from context, not from parent props
Tailwind remains the source of truth: All styling is in classes, not prop logic
Explicit composition: You see exactly what the card contains by reading the JSX

This matters for multi-tenant AI dashboards because tenant A's "Sentiment Analysis" widget might need a heatmap in the card body, while tenant B's "Document Classifier" needs a table. Same card structure, completely different content and layout.

Building the Compound Card System

Here's how I structure this in CitizenApp:

// CardContext.ts
import { createContext, useContext } from 'react';

interface CardContextType {
  isLoading?: boolean;
  variant?: 'default' | 'elevated' | 'outlined';
  isCompact?: boolean;
}

const CardContext = createContext<CardContextType | undefined>(undefined);

export function useCardContext() {
  const context = useContext(CardContext);
  if (!context) {
    throw new Error('Card compound components must be used within <Card>');
  }
  return context;
}

export { CardContext };

Why I define context this way: I keep it minimal. Only state that's truly shared across the card family lives here. Individual styling—padding, colors, borders—all stay in Tailwind classes at the consumption site.

// Card.tsx
import { ReactNode } from 'react';
import { CardContext } from './CardContext';

interface CardProps {
  children: ReactNode;
  isLoading?: boolean;
  variant?: 'default' | 'elevated' | 'outlined';
  isCompact?: boolean;
  className?: string;
}

export function Card({
  children,
  isLoading = false,
  variant = 'default',
  isCompact = false,
  className = '',
}: CardProps) {
  const contextValue = {
    isLoading,
    variant,
    isCompact,
  };

  // Variant base styles—these are *always* applied
  const variantClasses = {
    default: 'bg-white border border-gray-200',
    elevated: 'bg-white shadow-lg',
    outlined: 'bg-gray-50 border-2 border-gray-300',
  }[variant];

  return (
    <CardContext.Provider value={contextValue}>
      <div
        className={`rounded-lg overflow-hidden transition-opacity ${
          isLoading ? 'opacity-60 pointer-events-none' : 'opacity-100'
        } ${variantClasses} ${className}`}
        role={isLoading ? 'status' : undefined}
        aria-busy={isLoading}
      >
        {children}
      </div>
    </CardContext.Provider>
  );
}

Notice: the Card component is dumb about internal layout. It doesn't assume how many children or what order. It provides context and applies only the universal styles (border, shadow, loading state). Everything else is delegated to Tailwind at the consumption site.

// CardHeader.tsx
import { ReactNode } from 'react';
import { useCardContext } from './CardContext';

interface CardHeaderProps {
  children: ReactNode;
  className?: string;
}

export function CardHeader({ children, className = '' }: CardHeaderProps) {
  const { isCompact } = useCardContext();

  const compactPadding = isCompact ? 'px-4 py-2' : 'px-6 py-4';

  return (
    <div className={`border-b border-gray-200 ${compactPadding} ${className}`}>
      {children}
    </div>
  );
}

Here's the subtle magic: CardHeader uses context to read isCompact, which changes padding. The parent Card doesn't pass this as a prop. The header pulls what it needs. This is why compound components are superior to prop drilling—each component is self-aware.

// CardBody.tsx
import { ReactNode } from 'react';
import { useCardContext } from './CardContext';

interface CardBodyProps {
  children: ReactNode;
  className?: string;
}

export function CardBody({ children, className = '' }: CardBodyProps) {
  const { isCompact, isLoading } = useCardContext();

  const compactPadding = isCompact ? 'p-4' : 'p-6';

  return (
    <div
      className={`${compactPadding} ${isLoading ? 'blur-sm' : ''} ${className}`}
    >
      {children}
    </div>
  );
}

// CardFooter.tsx
import { ReactNode } from 'react';

interface CardFooterProps {
  children: ReactNode;
  className?: string;
}

export function CardFooter({ children, className = '' }: CardFooterProps) {
  return (
    <div
      className={`border-t border-gray-200 px-6 py-4 bg-gray-50 flex justify-end gap-2 ${className}`}
    >
      {children}
    </div>
  );
}

Now here's real usage from CitizenApp's Sentiment Analysis widget:

// SentimentDashboard.tsx
import { Card, CardHeader, CardBody, CardFooter } from '@/components/Card';
import { Button } from '@/components/Button';
import { HeatmapChart } from './HeatmapChart';

export function SentimentWidget() {
  const [isLoading, setIsLoading] = useState(false);

  return (
    <Card isLoading={isLoading} variant="elevated" className="h-full">
      <CardHeader className="flex justify-between items-center">
        <h2 className="text-lg font-semibold text-gray-900">
          Sentiment Trends
        </h2>
        <span className="text-sm text-gray-500">Last 30 days</span>
      </CardHeader>

      <CardBody className="space-y-4">
        <div className="grid grid-cols-3 gap-4">
          <div className="bg-green-50 p-4 rounded">
            <p className="text-xs text-gray-600">Positive</p>
            <p className="text-2xl font-bold text-green-600">68%</p>
          </div>
          <div className="bg-yellow-50 p-4 rounded">
            <p className="text-xs text-gray-600">Neutral</p>
            <p className="text-2xl font-bold text-yellow-600">24%</p>
          </div>
          <div className="bg-red-50 p-4 rounded">
            <p className="text-xs text-gray-600">Negative</p>
            <p className="text-2xl font-bold text-red-600">8%</p>
          </div>
        </div>

        <HeatmapChart />
      </CardBody>

      <CardFooter>
        <Button
          variant="secondary"
          onClick={() => setIsLoading(true)}
          onComplete={() => setIsLoading(false)}
        >
          Refresh Analysis
        </Button>
      </CardFooter>
    </Card>
  );
}

See what happened? The consumer entirely controls the layout of CardBody's interior. We didn't need a bodyClassName prop passed down. We just wrote the grid directly. This is composability.

The Gotcha: Context Overhead Isn't Zero

Here's what burned me initially: I thought compound components would be faster than prop drilling, but in a heavily re-rendering dashboard (AI features polling for updates), context updates on the root Card still cause all children to re-render.

The fix? Memoize aggressively:

const CardHeaderMemo = memo(CardHeader);
const CardBodyMemo = memo(CardBody);
const CardFooterMemo = memo(CardFooter);

export { CardHeaderMemo as CardHeader, CardBodyMemo as CardBody, CardFooterMemo as CardFooter };

And in your widget, memoize the Card's children if they're expensive:

<Card isLoading={isLoading}>
  <CardHeader>{/* ... */}</CardHeader>
  <CardBodyMemo>{/* Heavy chart rendering */}</CardBodyMemo>
  <CardFooter>{/* ... */}</CardFooter>
</Card>

Why Not Just Props?

Someone will ask: "Why not just make Card accept headerClassName, bodyClassName, etc.?" The answer is maintainability at scale. At

Render PostgreSQL Backups to S3: Automating Disaster Recovery for Multi-Tenant SaaS Without Vendor Lock-In

Ugur Aslim — Tue, 09 Jun 2026 08:11:16 +0000

Render PostgreSQL Backups to S3: Automating Disaster Recovery for Multi-Tenant SaaS Without Vendor Lock-In

I've been building CitizenApp on Render for two years. The platform is solid—zero complaints about uptime or developer experience. But I'll be honest: the first time I read Render's backup documentation, I realized I was entirely dependent on their infrastructure for data recovery.

That terrified me.

Here's the thing: Render's managed PostgreSQL comes with daily backups, but they're stored in their infrastructure. If Render experiences a catastrophic failure (unlikely, but possible), or if they discontinue the service, or if I need to migrate to another provider—I'm at their mercy. For CitizenApp, which handles sensitive tenant data across 200+ organizations, this isn't acceptable.

I'm not paranoid. I'm just someone who's read enough incident reports.

Why You Can't Sleep Well With Platform-Only Backups

Render's backup system is reliable for Render's purposes. They retain backups for 30 days, support point-in-time recovery (PITR), and honestly, their restoration process works smoothly. But there's a fundamental asymmetry: they control the backup, they control the restore, and they decide how long data lives.

Here's what keeps me awake:

Vendor lock-in: Your data is only as portable as Render's export capabilities
Compliance: SOC 2 audits often require evidence that backups exist outside the primary infrastructure
Recovery time objectives (RTO): Platform outages mean you can't restore even if you have backups
Cost surprises: Render might price backup storage differently next year
Multi-region redundancy: A single region failure shouldn't cascade to your recovery capability

For CitizenApp's clients, especially enterprises, I need to answer this question with confidence: "If Render evaporates tomorrow, how fast can we restore your data?" The honest answer with platform-only backups is: "We're probably okay, but I can't guarantee it."

So I automated offsite backups. Here's how.

The Architecture: Dump, Upload, Verify

I prefer a push-based model over trying to hook into Render's backup system directly. Here's why:

Simplicity: One scheduled job, no complex WAL archiving setup
Portability: Works with any PostgreSQL, not Render-specific
Auditability: I can see exactly what backed up and when
Cost control: S3/R2 storage is predictable and cheap

The flow looks like this:

PostgreSQL on Render
    ↓
pg_dump (compressed)
    ↓
Encrypt with age
    ↓
Upload to Cloudflare R2 (or AWS S3)
    ↓
Verify checksum & log
    ↓
Alert if failed

Setting Up Automated Backups

Step 1: Create an S3-Compatible Bucket

I use Cloudflare R2 because egress is free (S3 charges $0.09/GB). For CitizenApp, that's the difference between $10/month and $50/month at our current data size.

# AWS S3 (if you prefer)
aws s3 mb s3://citizenapp-postgres-backups-prod

# Cloudflare R2
# Done via dashboard, bucket: citizenapp-postgres-backups-prod

Create an IAM user with restricted permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::citizenapp-postgres-backups-prod",
        "arn:aws:s3:::citizenapp-postgres-backups-prod/*"
      ]
    }
  ]
}

Step 2: Python Backup Script

This runs daily via GitHub Actions (or a cron job elsewhere). I prefer GitHub Actions because it's free, version-controlled, and doesn't require managing another server.

# backup_postgres.py
import os
import subprocess
import hashlib
import sys
from datetime import datetime
import boto3
from pathlib import Path

def backup_postgres(db_url: str, bucket: str, region: str = "us-east-1") -> bool:
    """
    Backup PostgreSQL to S3-compatible storage.
    Returns True if successful.
    """
    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
    backup_file = f"/tmp/citizenapp_backup_{timestamp}.sql.gz"
    checksum_file = f"{backup_file}.sha256"

    try:
        # Step 1: Dump with compression
        print(f"[{timestamp}] Starting pg_dump...")
        subprocess.run(
            [
                "pg_dump",
                "--format=plain",
                "--compress=9",
                "--no-password",
                db_url,
            ],
            stdout=open(backup_file, "wb"),
            stderr=subprocess.PIPE,
            check=True,
        )

        file_size_mb = Path(backup_file).stat().st_size / (1024 * 1024)
        print(f"Dump complete: {file_size_mb:.2f} MB")

        # Step 2: Calculate checksum
        print("Calculating checksum...")
        sha256_hash = hashlib.sha256()
        with open(backup_file, "rb") as f:
            for chunk in iter(lambda: f.read(4096), b""):
                sha256_hash.update(chunk)

        checksum = sha256_hash.hexdigest()
        with open(checksum_file, "w") as f:
            f.write(f"{checksum}  {os.path.basename(backup_file)}\n")

        # Step 3: Upload to S3
        print(f"Uploading to S3 ({bucket})...")
        s3_client = boto3.client(
            "s3",
            region_name=region,
            endpoint_url=os.getenv("S3_ENDPOINT_URL"),  # For R2
            aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
            aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
        )

        s3_client.upload_file(
            backup_file,
            bucket,
            f"backups/{timestamp}.sql.gz",
            ExtraArgs={
                "Metadata": {
                    "checksum": checksum,
                    "size-mb": str(file_size_mb),
                }
            },
        )

        s3_client.upload_file(
            checksum_file,
            bucket,
            f"backups/{timestamp}.sql.gz.sha256",
        )

        print(f"✓ Backup successful: {timestamp}")
        print(f"  Checksum: {checksum}")

        # Step 4: Cleanup
        os.remove(backup_file)
        os.remove(checksum_file)

        return True

    except subprocess.CalledProcessError as e:
        print(f"✗ pg_dump failed: {e.stderr.decode()}")
        return False
    except Exception as e:
        print(f"✗ Backup failed: {str(e)}")
        return False

if __name__ == "__main__":
    db_url = os.getenv("DATABASE_URL")
    bucket = os.getenv("BACKUP_BUCKET", "citizenapp-postgres-backups-prod")
    region = os.getenv("BACKUP_REGION", "us-east-1")

    success = backup_postgres(db_url, bucket, region)
    sys.exit(0 if success else 1)

Step 3: GitHub Actions Workflow

# .github/workflows/backup-postgres.yml
name: Backup PostgreSQL to S3

on:
  schedule:
    - cron: "0 2 * * *"  # 2 AM UTC daily
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install boto3 psycopg2-binary

      - name: Run backup
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          AWS_ACCESS_KEY_ID: ${{ secrets.BACKUP_AWS_ACCESS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.BACKUP_AWS_SECRET_KEY }}
          S3_ENDPOINT_URL: ${{ secrets.BACKUP_S3_ENDPOINT }}
          BACKUP_BUCKET: ${{ secrets.BACKUP_BUCKET }}
        run: python scripts/backup_postgres.py

      - name: Notify on failure
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            const slack_webhook = "${{ secrets.SLACK_WEBHOOK_BACKUPS }}";
            await fetch(slack_webhook, {
              method: "POST",
              body: JSON.stringify({
                text: "⚠️ PostgreSQL backup failed for CitizenApp"
              })
            });

Testing Recovery (The Part Everyone Skips)

Here's the critical thing: a backup you've never restored is just hope. I test recovery quarterly.


bash
# Download and verify
aws s3 cp s3://citizenapp-postgres-backups-prod/backups/20240115_020000.sql.gz .
sha256sum -c <(echo "abc123... 20240115_020000.sql.gz")

# Restore to a test database
gunzip -c 20240115_020000.sql.

PostgreSQL Foreign Key Cycles in Multi-Tenant Hierarchies: Breaking Circular Dependencies Without Violating Referential Integrity

Ugur Aslim — Mon, 08 Jun 2026 08:25:47 +0000

PostgreSQL Foreign Key Cycles in Multi-Tenant Hierarchies: Breaking Circular Dependencies Without Violating Referential Integrity

I hit this problem hard in CitizenApp. We needed users to belong to teams, teams to have manager users, and managers to delegate permissions back through teams. Sounds reasonable, right? PostgreSQL said no.

The naive schema looks clean on paper:

CREATE TABLE teams (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  name VARCHAR(255) NOT NULL,
  manager_id UUID NOT NULL REFERENCES users(id),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

CREATE TABLE users (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  email VARCHAR(255) NOT NULL,
  team_id UUID NOT NULL REFERENCES teams(id),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

Try inserting data and watch it explode:

ERROR: insert or update on table "teams" violates foreign key constraint
FOREIGN KEY (manager_id) REFERENCES users(id)

You can't insert a user without a team. You can't insert a team without a user manager. Welcome to circular hell.

Why This Matters (Beyond the Error)

I've seen three bad production approaches to this:

Soft deletes everywhere — "We'll just mark things as deleted instead of cascading." Now your queries are littered with AND deleted_at IS NULL. Your indexes are bloated. Your team hates you.
Nullable foreign keys — Set manager_id NULL initially. But now you've violated your actual business constraint (every team must have a manager). Your application becomes the database.
No foreign keys — "We'll just trust the app." I've watched this drift into data chaos within six months.

There's a fourth way: DEFERRABLE constraints with transaction-level validation. This is what I use in CitizenApp, and it's been solid.

The Solution: DEFERRABLE INITIALLY DEFERRED

PostgreSQL lets you declare foreign keys as DEFERRABLE INITIALLY DEFERRED. This means:

Foreign key checks happen at transaction commit, not at statement execution
Within a transaction, you can temporarily violate constraints
As long as everything is valid at COMMIT, you're golden
Referential integrity is still guaranteed—nothing weak about it

Here's the fixed schema:

CREATE TABLE teams (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL,
  name VARCHAR(255) NOT NULL,
  manager_id UUID NOT NULL REFERENCES users(id) 
    ON DELETE RESTRICT
    DEFERRABLE INITIALLY DEFERRED,
  FOREIGN KEY (tenant_id) REFERENCES tenants(id),
  UNIQUE(tenant_id, name)
);

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL,
  email VARCHAR(255) NOT NULL,
  team_id UUID NOT NULL REFERENCES teams(id)
    ON DELETE RESTRICT
    DEFERRABLE INITIALLY DEFERRED,
  FOREIGN KEY (tenant_id) REFERENCES tenants(id),
  UNIQUE(tenant_id, email)
);

Notice: both foreign keys are DEFERRABLE INITIALLY DEFERRED. The ON DELETE RESTRICT is important—we never want orphaned records cascading silently.

Insertion Strategy: Create in the Right Order

Within a single transaction, order matters:

# FastAPI + SQLAlchemy example
from sqlalchemy import text
from sqlalchemy.orm import Session
import uuid

async def create_team_with_manager(
    db: Session,
    tenant_id: str,
    team_name: str,
    manager_email: str,
) -> dict:
    """
    Creates a team and its manager in a single transaction.
    The cycle (team → manager user → team) is resolved at commit.
    """
    team_id = str(uuid.uuid4())
    user_id = str(uuid.uuid4())

    try:
        # Step 1: Create the user WITHOUT team assignment
        # Temporarily violate the team_id constraint
        db.execute(
            text("""
            INSERT INTO users (id, tenant_id, email, team_id)
            VALUES (:id, :tenant_id, :email, :team_id)
            """),
            {
                "id": user_id,
                "tenant_id": tenant_id,
                "email": manager_email,
                "team_id": team_id,  # Will reference team created next
            }
        )

        # Step 2: Create the team pointing to the user
        db.execute(
            text("""
            INSERT INTO teams (id, tenant_id, name, manager_id)
            VALUES (:id, :tenant_id, :name, :manager_id)
            """),
            {
                "id": team_id,
                "tenant_id": tenant_id,
                "name": team_name,
                "manager_id": user_id,
            }
        )

        # Step 3: Update the user's team_id to the correct team
        db.execute(
            text("""
            UPDATE users SET team_id = :team_id WHERE id = :id
            """),
            {"team_id": team_id, "id": user_id}
        )

        db.commit()

        return {
            "team_id": team_id,
            "user_id": user_id,
            "team_name": team_name,
            "manager_email": manager_email,
        }

    except Exception as e:
        db.rollback()
        raise ValueError(f"Failed to create team: {str(e)}")

Wait—that's three steps. Can we do better? Absolutely. Use a prepared transaction or a function:

CREATE FUNCTION create_team_with_manager(
  p_tenant_id UUID,
  p_team_name VARCHAR,
  p_manager_email VARCHAR
) RETURNS TABLE (team_id UUID, user_id UUID) AS $$
DECLARE
  v_team_id UUID := gen_random_uuid();
  v_user_id UUID := gen_random_uuid();
BEGIN
  -- Insert user first, pointing to team that doesn't exist yet
  INSERT INTO users (id, tenant_id, email, team_id)
  VALUES (v_user_id, p_tenant_id, p_manager_email, v_team_id);

  -- Now insert team pointing to user
  INSERT INTO teams (id, tenant_id, name, manager_id)
  VALUES (v_team_id, p_tenant_id, p_team_name, v_user_id);

  RETURN QUERY SELECT v_team_id, v_user_id;
END;
$$ LANGUAGE plpgsql;

The function wraps everything in one logical transaction. Call it from Python:

async def create_team_with_manager_simple(
    db: Session,
    tenant_id: str,
    team_name: str,
    manager_email: str,
) -> dict:
    result = db.execute(
        text("""
        SELECT team_id, user_id 
        FROM create_team_with_manager(:tenant_id, :team_name, :manager_email)
        """),
        {
            "tenant_id": tenant_id,
            "team_name": team_name,
            "manager_email": manager_email,
        }
    ).fetchone()

    db.commit()
    return {"team_id": str(result[0]), "user_id": str(result[1])}

Deleting: Watch the Cascade

This is where ON DELETE RESTRICT saves you:

-- This will FAIL at commit if the user is still a manager
DELETE FROM users WHERE id = ?;
-- PostgreSQL: Cannot delete user while still managing a team

You must delete the team first, or reassign the manager:

async def delete_team(db: Session, team_id: str):
    # Reassign manager to a different team, or NULL (if allowed)
    db.execute(
        text("UPDATE teams SET manager_id = NULL WHERE id = :id"),
        {"id": team_id}
    )

    # Now safe to delete
    db.execute(
        text("DELETE FROM teams WHERE id = :id"),
        {"id": team_id}
    )

    db.commit()

This is exactly what you want—explicit, intentional, no silent cascades.

Gotcha: DEFERRABLE Only Works Within Transactions

This burned me: I tested locally (wrapped in transactions), deployed to production, and found that single-statement inserts outside transactions still fail:

# This FAILS even with DEFERRABLE INITIALLY DEFERRED
user = User(id=user_id, team_id=team_id)
db.add(user)
db.flush()  # Checked immediately, not deferred!

The trick: Always wrap multi-step operations in explicit transactions:

from contextlib import contextmanager

@contextmanager
def atomic_transaction(db: Session):
    try:
        yield db
        db.commit()
    except Exception:
        db.rollback()
        raise

# Usage
with atomic_transaction(db) as session:
    create_team_with_manager(session, ...)

Why Not Soft Deletes or NULLs?

Soft deletes pollute every query and hide actual data shape
Nullable FKs mean your database doesn't enforce your actual constraints
DEFERRABLE enforces referential integrity and allows cycles without workarounds

It's the cleaner architectural choice. I've used this pattern across CitizenApp's tenant hierarchies (8 months, no integrity issues, no maintenance headaches).

Use it. Your future self will thank you.

FastAPI Request Logging for Multi-Tenant Debugging: Structured Logs That Preserve Tenant Context Without Middleware Chaos

Ugur Aslim — Sun, 07 Jun 2026 17:53:23 +0000

FastAPI Request Logging for Multi-Tenant Debugging: Structured Logs That Preserve Tenant Context Without Middleware Chaos

I've spent three weeks digging through 50MB of unstructured text logs trying to figure out why one tenant's Claude API call was poisoning request contexts for everyone else. That week taught me that logging infrastructure is not optional when you're running multi-tenant SaaS at scale—it's the difference between a 30-second fix and a 3-day investigation.

The problem is this: standard FastAPI logging with print statements or basic Python logging spills context everywhere. When tenant A's AI feature call fails, you can't quickly trace which of your 50 concurrent requests it affected. By the time you grep for error messages, you're wading through logs from 12 other tenants. I prefer structured JSON logging with automatic context injection because it makes every log line queryable and tenant-scoped without littering your handler code with context parameters.

Why Unstructured Logging Fails at Multi-Tenant Scale

Most FastAPI projects start with this:

import logging
logger = logging.getLogger(__name__)

@app.post("/api/insights")
async def generate_insights(req: InsightRequest):
    logger.info(f"User {req.user_id} requested insights")
    # ... API call to Claude
    logger.error(f"Claude API failed: {error}")

This burns you the moment you ship to production. Here's why:

Tenant context is invisible. You log a Claude error but can't immediately see which tenant owns that user. Grep becomes your life.
Request ID is missing. When one request spawns async tasks, you lose the thread. Which log lines belong together?
Context leaks across requests. Python's contextvars aren't automatically populated. If you forget to set context in one code path, logs from concurrent requests bleed together.
AI feature context is scattered. You're calling Claude, making database queries, updating caches—but logs don't tell you which operation stage failed or how long each took.

Structured JSON logging solves all of this because:

Every log line is a queryable object with tenant_id, user_id, request_id baked in.
You can search by JSON field: tenant_id:"acme-corp" instead of grepping for company names.
Context is injected automatically—no manual parameter passing through 8 function layers.
AI feature invocations become traceable events, not scattered print statements.

Architecture: Context Vars + JSON Logging + Middleware

Here's the pattern I use in CitizenApp:

# logging_config.py
import json
import logging
import contextvars
import uuid
from typing import Any, Dict
from datetime import datetime

# Context variables that persist across async function calls
tenant_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
    "tenant_id", default="unknown"
)
user_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
    "user_id", default="unknown"
)
request_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
    "request_id", default=str(uuid.uuid4())
)
feature_var: contextvars.ContextVar[str] = contextvars.ContextVar(
    "feature", default="unknown"
)


class StructuredLogger(logging.Formatter):
    """Formats logs as JSON with automatic context injection."""

    def format(self, record: logging.LogRecord) -> str:
        log_data: Dict[str, Any] = {
            "timestamp": datetime.utcnow().isoformat(),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "tenant_id": tenant_id_var.get(),
            "user_id": user_id_var.get(),
            "request_id": request_id_var.get(),
            "feature": feature_var.get(),
        }

        # Add exception info if present
        if record.exc_info:
            log_data["exception"] = self.formatException(record.exc_info)

        # Allow handlers to inject extra fields
        if hasattr(record, "extra_fields"):
            log_data.update(record.extra_fields)

        return json.dumps(log_data)


def configure_logging():
    """Initialize structured logging."""
    handler = logging.StreamHandler()
    handler.setFormatter(StructuredLogger())

    root_logger = logging.getLogger()
    root_logger.setLevel(logging.INFO)
    root_logger.addHandler(handler)

    return logging.getLogger(__name__)


logger = configure_logging()

Now the middleware that populates context:

# middleware.py
from fastapi import Request, HTTPException
from fastapi.responses import JSONResponse
import time
import uuid
from logging_config import (
    tenant_id_var, user_id_var, request_id_var,
    feature_var, logger
)


@app.middleware("http")
async def add_request_context(request: Request, call_next):
    """Extract tenant/user from request and populate context vars."""
    request_id = str(uuid.uuid4())
    request_id_var.set(request_id)

    # Extract tenant from path or header
    # In CitizenApp, tenants are identified by subdomain or header
    tenant_id = request.headers.get("X-Tenant-ID", "unknown")
    tenant_id_var.set(tenant_id)

    # Extract user from JWT token or session
    user_id = request.headers.get("X-User-ID", "unknown")
    user_id_var.set(user_id)

    start_time = time.time()
    try:
        response = await call_next(request)
    except Exception as e:
        logger.error(f"Request failed: {str(e)}")
        raise
    finally:
        # Log request completion with duration
        duration = time.time() - start_time
        logger.info(
            f"{request.method} {request.url.path} completed",
            extra={"extra_fields": {"duration_ms": duration * 1000, "status": response.status_code}}
        )

    return response

The middleware does one job: extract tenant and user from the request and populate context vars. Everything downstream automatically inherits this context.

Using It in Your Handlers

Now when you log in handlers, context is automatic:

# handlers.py
from fastapi import APIRouter, Depends
from logging_config import logger, feature_var
import anthropic

router = APIRouter()


@router.post("/api/generate-insights")
async def generate_insights(tenant_id: str, user_id: str, req: InsightRequest):
    """
    Generate AI insights for a tenant's data.
    Every log line is automatically tagged with tenant_id, user_id, request_id.
    """
    feature_var.set("insights-generation")

    logger.info("Starting insights generation")

    try:
        # Call Claude API
        client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
        message = await client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": f"Analyze this data: {req.data}"
                }
            ],
        )
        logger.info("Claude API call succeeded", extra={
            "extra_fields": {"tokens_used": message.usage.output_tokens}
        })

        # Save results to database
        insights = await save_insights(tenant_id, user_id, message.content)
        logger.info("Insights saved to database")

        return {"insights": insights}

    except anthropic.APIError as e:
        logger.error(f"Claude API error: {str(e)}")
        raise HTTPException(status_code=502, detail="AI service unavailable")
    except Exception as e:
        logger.error(f"Unexpected error: {str(e)}")
        raise

Notice: no manual context passing. No log_context(tenant_id=...) calls everywhere. The logger automatically includes tenant_id, user_id, request_id, and feature because contextvars preserves them across async boundaries.

The output looks like this:

{
  "timestamp": "2024-01-15T10:23:45.123456",
  "level": "INFO",
  "logger": "handlers",
  "message": "Starting insights generation",
  "tenant_id": "acme-corp",
  "user_id": "user-123",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "feature": "insights-generation"
}

When Claude fails, you immediately see which tenant, which user, which request. If multiple errors occurred, they all share the same request_id, making it trivial to correlate.

Querying Structured Logs

This is where structured logging shines. With Render's log streaming or any centralized logging service (I use Datadog in production), you can query by field:

tenant_id:"acme-corp" AND level:"ERROR"

Versus unstructured grep hell:

grep "acme-corp\|ACME\|error" logs.txt | head -100 | grep -v other_tenants...

Gotcha: Context Vars Don't Persist to Background Tasks

This bit me hard. When you spawn a background task with asyncio.create_task(), the context vars don't automatically propagate:

# WRONG - loses context in background task
asyncio.create_task(process_results_async(results))

# RIGHT - explicitly copy context
import copy_context
ctx = copy_context()
asyncio.create_task(ctx.run(process_results_async, results))

In CitizenApp, I wrap all background task spawning in a helper:


python
def spawn_background_task(coro):
    """Spawn background task preserving context vars."""
    ctx = copy_context()
    asyncio.create

PostgreSQL Window Functions for Multi-Tenant Feature Adoption Analytics: Ranking Users Without Application-Layer Sorting

Ugur Aslim — Sun, 07 Jun 2026 17:52:51 +0000

PostgreSQL Window Functions for Multi-Tenant Feature Adoption Analytics: Ranking Users Without Application-Layer Sorting

I used to pull raw user engagement data into Python, sort it in memory, and compute rankings. It worked until it didn't—a customer with 50K users made my FastAPI endpoint timeout, and I realized I was doing analytics like it was 2005.

Window functions changed how I think about metrics. They let you compute per-tenant rankings, adoption curves, and cohort retention in a single SQL pass. No application-layer sorting, no memory bloat, no distributed processing headaches. Just SQL doing what it's actually good at.

Here's what I learned shipping CitizenApp's adoption analytics with PostgreSQL window functions.

Why Window Functions Matter for Multi-Tenant SaaS

When you're computing feature adoption metrics across tenants, you need to:

Rank users within each tenant by engagement (ROW_NUMBER, RANK)
Calculate adoption curves (when did each user adopt a feature?)
Track cohort retention (compare users from the same signup week)
Identify trending features per tenant

You could load all user events into Python, group by tenant, sort, and compute. But that's memory-intensive, slow, and doesn't scale. Window functions do this in the database where it belongs.

I prefer window functions because:

Single SQL pass: No round-trips to the application
Stateless endpoints: FastAPI doesn't hold gigabytes of data
Sub-millisecond queries: PostgreSQL optimizes window function execution
Tenant isolation baked in: PARTITION BY tenant_id keeps data separate

Real Example: Feature Adoption Rankings

Let's say you track feature usage like this:

CREATE TABLE feature_events (
  id BIGSERIAL PRIMARY KEY,
  tenant_id UUID NOT NULL,
  user_id UUID NOT NULL,
  feature_name TEXT NOT NULL,
  event_date DATE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_feature_events_tenant_user_date 
  ON feature_events(tenant_id, user_id, event_date);

Without window functions, you'd do something like this (don't do this):

# BAD: Pulls everything into memory, sorts in Python
result = db.query(FeatureEvent).filter(
    FeatureEvent.tenant_id == tenant_id
).all()

user_counts = {}
for event in result:
    user_counts[event.user_id] = user_counts.get(event.user_id, 0) + 1

ranked = sorted(user_counts.items(), key=lambda x: x[1], reverse=True)
return [(uid, count, rank) for rank, (uid, count) in enumerate(ranked, 1)]

This breaks at scale. Here's the window function approach:

WITH user_event_counts AS (
  SELECT
    tenant_id,
    user_id,
    COUNT(*) as event_count,
    MAX(event_date) as last_event_date
  FROM feature_events
  WHERE tenant_id = $1
  GROUP BY tenant_id, user_id
)
SELECT
  user_id,
  event_count,
  last_event_date,
  ROW_NUMBER() OVER (
    PARTITION BY tenant_id 
    ORDER BY event_count DESC
  ) as engagement_rank,
  RANK() OVER (
    PARTITION BY tenant_id 
    ORDER BY event_count DESC
  ) as engagement_rank_with_ties,
  COUNT(*) OVER (PARTITION BY tenant_id) as total_active_users
FROM user_event_counts
ORDER BY engagement_rank
LIMIT 100;

This executes in milliseconds. The PARTITION BY tenant_id ensures each tenant's ranking is independent—crucial for multi-tenancy.

Here's the FastAPI wrapper:

// TypeScript client-side type
interface UserEngagement {
  user_id: string;
  event_count: number;
  last_event_date: string;
  engagement_rank: number;
  engagement_rank_with_ties: number;
  total_active_users: number;
}

from fastapi import FastAPI, Depends
from sqlalchemy import text
from typing import List

@app.get("/api/tenants/{tenant_id}/engagement/rankings")
async def get_engagement_rankings(
    tenant_id: UUID,
    current_tenant: Tenant = Depends(verify_tenant_access),
    skip: int = 0,
    limit: int = 100
) -> List[UserEngagement]:
    query = text("""
    WITH user_event_counts AS (
      SELECT
        tenant_id,
        user_id,
        COUNT(*) as event_count,
        MAX(event_date) as last_event_date
      FROM feature_events
      WHERE tenant_id = :tenant_id
      GROUP BY tenant_id, user_id
    )
    SELECT
      user_id,
      event_count,
      last_event_date,
      ROW_NUMBER() OVER (
        PARTITION BY tenant_id 
        ORDER BY event_count DESC
      ) as engagement_rank,
      COUNT(*) OVER (PARTITION BY tenant_id) as total_active_users
    FROM user_event_counts
    ORDER BY engagement_rank
    LIMIT :limit OFFSET :skip
    """)

    result = db.execute(query, {
        "tenant_id": str(tenant_id),
        "limit": limit,
        "skip": skip
    })
    return [UserEngagement(**row) for row in result]

LAG/LEAD for Adoption Curves

When did each user first adopt a feature? Compute feature adoption funnels directly:

SELECT
  tenant_id,
  user_id,
  feature_name,
  MIN(event_date) as first_adoption_date,
  DATEDIFF(day, 
    LAG(MIN(event_date)) OVER (
      PARTITION BY tenant_id, user_id 
      ORDER BY MIN(event_date)
    ),
    MIN(event_date)
  ) as days_to_next_feature
FROM feature_events
WHERE tenant_id = $1
GROUP BY tenant_id, user_id, feature_name
ORDER BY user_id, first_adoption_date;

This shows when each user adopted each feature and how many days between adopting features. No Python loops needed.

Gotcha: PARTITION BY Order Matters

This burned me: I assumed PARTITION BY controlled result order. It doesn't.

-- WRONG: Results aren't ordered within partition
SELECT user_id, event_count,
  ROW_NUMBER() OVER (PARTITION BY tenant_id ORDER BY event_count DESC)
FROM ...
-- Missing ORDER BY at the end!

-- RIGHT
SELECT user_id, event_count,
  ROW_NUMBER() OVER (PARTITION BY tenant_id ORDER BY event_count DESC)
FROM ...
ORDER BY tenant_id, engagement_rank;

Always add ORDER BY at the query level, especially with LIMIT. PostgreSQL doesn't guarantee row order without it.

What I Missed: Frame Specifications

I initially didn't use window frame specifications (ROWS BETWEEN). This matters for running averages:

SELECT
  user_id,
  event_date,
  event_count,
  -- Running 7-day average engagement
  AVG(event_count) OVER (
    PARTITION BY tenant_id, user_id
    ORDER BY event_date
    ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
  ) as rolling_7day_avg
FROM daily_user_events
ORDER BY user_id, event_date;

Without the frame specification, AVG() computes across the entire partition (unbounded). With it, you get a proper rolling window.

The Result

Since switching to window functions for CitizenApp's analytics dashboard:

Query time: 8 seconds → 120ms (per-tenant adoption metrics)
Memory footprint: 2GB spike on large queries → consistent 50MB
Endpoint latency: P99 at 15s → P99 at 400ms
Infrastructure: Killed the background worker that was sorting in Celery

Window functions aren't flashy. They're not trendy. But they're one of the highest-ROI database optimizations for SaaS analytics. If you're sorting aggregated data in application code, stop. Move it to SQL.

React 19 Lazy Component Loading for Feature Flags: Conditionally Shipping Code Only to Tenants Who Can Use It

Ugur Aslim — Sun, 07 Jun 2026 17:52:43 +0000

React 19 Lazy Component Loading for Feature Flags: Conditionally Shipping Code Only to Tenants Who Can Use It

Feature flags and code splitting are two separate problems most teams solve independently. Feature flags control access, code splitting controls payload. But here's the gap: you can have both—by lazy-loading React components only for tenants who can actually use them, you solve the bundle size problem and prevent accidental exposure of paid features to free users in a single move.

I've burned myself on this twice in CitizenApp. The first time, I shipped an entire AI feature module (Claude integration for document analysis) to free users even though the backend properly gated it. A clever user read the bundle, found the endpoint, and started making API calls. The second time, I had feature flags for access control but lazy-loaded everything, which meant free users were downloading React components they'd never render. React 19's lazy() paired with tenant feature flags fixes both problems elegantly.

The Problem: Feature Flags and Code Splitting Are Not the Same Thing

Let me be clear: feature flags are not code splitting.

A feature flag checks user.tier === 'pro' at runtime and conditionally renders a component. The component code still shipped in your bundle. You've prevented access but not payload bloat.

Code splitting with React.lazy() and Suspense delays loading a chunk until the component is mounted. But if you lazy-load everything, free users still request the chunk when they navigate to a feature page (404 or permission denied). You've added latency and network overhead for features they can't use.

The two-step dance is:

Feature flag check determines if the tenant should have access
Lazy loading ensures the component code only loads if the flag is true

If you skip step two, bundle bloat wins. If you skip step one, you've exposed code you shouldn't have.

The Solution: Lazy Components Gated by Tenant Flags

Here's the pattern I use in CitizenApp.

First, define your tenant's feature flags in a hook:

// hooks/useFeatureFlags.ts
import { useContext } from 'react';
import { TenantContext } from '../context/TenantContext';

export const useFeatureFlags = () => {
  const { tenant } = useContext(TenantContext);

  return {
    hasDocumentAI: tenant?.tier === 'pro' || tenant?.tier === 'enterprise',
    hasBulkAnalysis: tenant?.tier === 'enterprise',
    hasWebhooks: tenant?.tier === 'pro' || tenant?.tier === 'enterprise',
    hasCustomModels: tenant?.tier === 'enterprise',
  };
};

Why in a hook and not a context value directly? Because I want to co-locate the flag logic with the check. When a PM asks "who can use webhooks?", I jump to one line.

Next, lazy-load your feature components:

// components/FeatureLoader.tsx
import { lazy, Suspense, ReactNode } from 'react';
import { useFeatureFlags } from '../hooks/useFeatureFlags';

// Only define these if the flag exists
const DocumentAI = lazy(() => 
  import('./features/DocumentAI').then(mod => ({ default: mod.DocumentAI }))
);

const BulkAnalysis = lazy(() => 
  import('./features/BulkAnalysis').then(mod => ({ default: mod.BulkAnalysis }))
);

interface FeatureLoaderProps {
  feature: keyof ReturnType<typeof useFeatureFlags>;
  fallback?: ReactNode;
  children?: ReactNode;
}

export const FeatureLoader = ({ 
  feature, 
  fallback = <div>Loading...</div>,
  children 
}: FeatureLoaderProps) => {
  const flags = useFeatureFlags();

  if (!flags[feature]) {
    return null; // Don't render, don't request the chunk
  }

  const componentMap = {
    hasDocumentAI: DocumentAI,
    hasBulkAnalysis: BulkAnalysis,
    hasWebhooks: () => <div>Webhooks feature</div>,
    hasCustomModels: () => <div>Custom models feature</div>,
  };

  const Component = componentMap[feature];

  if (!Component) {
    console.warn(`Unknown feature: ${feature}`);
    return null;
  }

  return (
    <Suspense fallback={fallback}>
      <Component />
    </Suspense>
  );
};

Now in your router or feature page:

// pages/dashboard.tsx
import { FeatureLoader } from '../components/FeatureLoader';

export default function Dashboard() {
  return (
    <div className="space-y-6">
      <h1>Features</h1>

      <FeatureLoader 
        feature="hasDocumentAI" 
        fallback={<div className="h-64 bg-gray-200 animate-pulse" />}
      />

      <FeatureLoader feature="hasBulkAnalysis" />

      <FeatureLoader feature="hasWebhooks" />
    </div>
  );
}

The magic: if tenant.tier === 'free', all flags are false. The component code is never requested. The chunk for DocumentAI.tsx never appears in the network tab. The browser never even knows it exists.

Backend Parity: Double-Check at the API Layer

This is critical: lazy-loading prevents accidental exposure, but it's not a security boundary. A motivated user can request the API endpoint directly.

Always validate the flag on the backend:

# FastAPI endpoint
from fastapi import HTTPException, Depends
from sqlalchemy.orm import Session

async def get_current_tenant(request: Request, db: Session = Depends(get_db)):
    token = request.headers.get("Authorization", "").replace("Bearer ", "")
    payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    tenant = db.query(Tenant).filter(Tenant.id == payload["tenant_id"]).first()
    if not tenant:
        raise HTTPException(status_code=401)
    return tenant

@app.post("/api/analyze-document")
async def analyze_document(
    file: UploadFile,
    tenant: Tenant = Depends(get_current_tenant),
    db: Session = Depends(get_db)
):
    # Check the flag server-side
    if tenant.tier not in ["pro", "enterprise"]:
        raise HTTPException(
            status_code=403, 
            detail="Document AI requires Pro tier"
        )

    # Process with Claude
    content = await file.read()
    message = await client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this document:"},
                {"type": "document", "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": base64.b64encode(content).decode()
                }}
            ]
        }]
    )
    return {"analysis": message.content[0].text}

The frontend lazy-load prevents bundle bloat and accidental exposure. The backend check prevents exploitation.

Gotcha: Lazy Components and TypeScript

This one bit me hard. When you lazy-load a component, TypeScript doesn't automatically infer its props:

// ❌ This won't work
const DocumentAI = lazy(() => import('./features/DocumentAI'));
// DocumentAI accepts props, but TS doesn't know that

// ✅ Do this instead
const DocumentAI = lazy(() => 
  import('./features/DocumentAI').then(mod => ({ default: mod.DocumentAI }))
);

Or define your lazy components with explicit typing:

// components/LazyFeatures.ts
import { lazy, ComponentType } from 'react';

interface DocumentAIProps {
  tenantId: string;
}

export const DocumentAI = lazy(
  () => import('./features/DocumentAI')
) as ComponentType<DocumentAIProps>;

Bundle Impact in Production

On CitizenApp, this pattern reduced the main bundle by 34KB (gzipped). For free users, the Document AI, Bulk Analysis, and Webhook modules never load—three separate chunks skipped entirely. The lazy-loaded chunks only materialize for pro users who navigate to the feature.

What I Missed the First Time

I tried to be clever and dynamically map feature names to components using a registry. Maintenance nightmare. Now I hardcode the component imports in FeatureLoader—boring but explicit. When you're debugging bundle issues or feature exposure, clarity wins every time.

Also, don't overthink tenant context. A simple object with tier and plan ID is enough. I used to store a massive feature capabilities object that required syncing with frontend code. Single source of truth is simpler: compute flags from tier.

The two-step dance—feature flags for access control, lazy loading for payload reduction—is the right way to ship tiered SaaS. Do both or do neither; doing just one leaves you exposed or bloated.

SQLAlchemy Event Listeners for Automatic Tenant Data Isolation: Enforcing Multi-Tenancy at the ORM Layer Without Manual Filtering

Ugur Aslim — Sun, 07 Jun 2026 17:52:05 +0000

SQLAlchemy Event Listeners for Automatic Tenant Data Isolation: Enforcing Multi-Tenancy at the ORM Layer Without Manual Filtering

I've shipped multi-tenant SaaS. I've also watched a junior developer accidentally expose Customer A's data to Customer B because they forgot a single filter(Tenant.id == current_tenant_id) clause in one endpoint. That's the moment I realized: manual tenant filtering is security theater.

Here's the uncomfortable truth: telling developers "just remember to filter by tenant_id in every query" is like telling drivers "just remember not to hit things." Human error is inevitable. The solution isn't better reminders—it's making the mistake physically impossible at the ORM layer.

SQLAlchemy event listeners let you enforce tenant isolation automatically. Every query gets the tenant filter injected before it even touches the database. A junior developer can't leak data even if they try.

The Problem with Manual Filtering

Let's say your endpoint looks like this:

@app.get("/users")
async def list_users(current_user: User = Depends(get_current_user)):
    users = db.query(User).filter(User.active == True).all()
    return users

Looks innocent. But there's a bug here—no tenant filter. That query returns every active user across all tenants. Customer A sees Customer B's employees. GDPR violation. Blog post about your security failure. CVE number. Your weekend is ruined.

You could add the filter:

users = db.query(User).filter(
    User.active == True,
    User.tenant_id == current_user.tenant_id
).all()

Better. But what about this endpoint? And this one? And the one added by the new hire who doesn't know about the tenant isolation pattern yet?

The problem multiplies across your codebase. Every developer has to remember. Every review has to catch it. Every new endpoint is a security risk until proven otherwise.

This is backwards. Security should be the default, not an afterthought.

The ORM-Layer Solution: Event Listeners

SQLAlchemy has an event system that hooks into the query lifecycle. I use before_bulk_update and before_delete to inject tenant filters automatically—before the database ever sees the query.

Here's the architecture:

from sqlalchemy import event
from sqlalchemy.orm import Query, Session
from contextlib import contextmanager

# Thread-local storage for current tenant context
_tenant_context = {}

@contextmanager
def tenant_context(tenant_id: int):
    """Context manager to set the current tenant."""
    _tenant_context['tenant_id'] = tenant_id
    try:
        yield
    finally:
        _tenant_context.pop('tenant_id', None)

def get_current_tenant_id() -> int | None:
    """Retrieve the current tenant from context."""
    return _tenant_context.get('tenant_id')

# Define a marker for multi-tenant tables
TENANT_AWARE = '__tenant_aware__'

def make_tenant_aware(cls):
    """Decorator to mark a model as tenant-aware."""
    setattr(cls, TENANT_AWARE, True)
    return cls

@make_tenant_aware
class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    tenant_id: Mapped[int] = mapped_column(ForeignKey("tenants.id"))
    email: Mapped[str]
    active: Mapped[bool] = mapped_column(default=True)

@make_tenant_aware
class Document(Base):
    __tablename__ = "documents"
    id: Mapped[int] = mapped_column(primary_key=True)
    tenant_id: Mapped[int] = mapped_column(ForeignKey("tenants.id"))
    title: Mapped[str]

Now the event listeners:

@event.listens_for(Session, "before_bulk_update")
def receive_before_bulk_update(update_context):
    """Inject tenant filter before bulk update."""
    mapper = update_context.mapper

    # Only filter tenant-aware models
    if not hasattr(mapper.class_, TENANT_AWARE):
        return

    tenant_id = get_current_tenant_id()
    if tenant_id is None:
        raise RuntimeError(
            f"Attempted to update {mapper.class_.__name__} "
            "without tenant context. Use tenant_context()."
        )

    # Inject the tenant filter
    update_context.whereclause = update_context.whereclause & (
        mapper.class_.tenant_id == tenant_id
    )

@event.listens_for(Session, "before_bulk_delete")
def receive_before_bulk_delete(delete_context):
    """Inject tenant filter before bulk delete."""
    mapper = delete_context.mapper

    if not hasattr(mapper.class_, TENANT_AWARE):
        return

    tenant_id = get_current_tenant_id()
    if tenant_id is None:
        raise RuntimeError(
            f"Attempted to delete {mapper.class_.__name__} "
            "without tenant context. Use tenant_context()."
        )

    # Inject the tenant filter
    delete_context.whereclause = delete_context.whereclause & (
        mapper.class_.tenant_id == tenant_id
    )

@event.listens_for(Session, "before_flush")
def receive_before_flush(session, flush_context, instances):
    """Validate that all tenant-aware objects have tenant_id set."""
    for obj in session.new | session.dirty:
        if hasattr(obj.__class__, TENANT_AWARE):
            if not hasattr(obj, 'tenant_id') or obj.tenant_id is None:
                raise RuntimeError(
                    f"{obj.__class__.__name__} missing tenant_id. "
                    "Tenant context not properly set."
                )

Usage: The Developer Experience

Your endpoint now becomes:

@app.get("/users")
async def list_users(current_user: User = Depends(get_current_user)):
    # This context manager sets the tenant for all queries within it
    with tenant_context(current_user.tenant_id):
        # No explicit tenant filter needed—it's automatic
        users = db.query(User).filter(User.active == True).all()
    return users

No filter forgotten. No data leak possible. If a developer tries to query without setting tenant context:

users = db.query(User).all()  # RuntimeError: Attempted to update User without tenant context

The code fails loudly. Not silently. Not after three months in production.

For FastAPI, wrap it in dependency injection:

async def get_db_session(current_user: User = Depends(get_current_user)):
    """Provide a session with tenant context already set."""
    with tenant_context(current_user.tenant_id):
        yield db

Now your endpoint is just:

@app.get("/users")
async def list_users(db: Session = Depends(get_db_session)):
    users = db.query(User).filter(User.active == True).all()
    return users

The tenant filter is invisible—which is exactly the point.

Gotcha: Unscoped Joins

This approach works for single-table queries. But joins can be tricky:

# This gets filtered automatically
users = db.query(User).all()

# But this might not, if Document isn't also tenant-aware
docs = db.query(Document).join(User).all()

The join doesn't automatically filter User. You need to either:

Mark both tables tenant-aware (preferred)
Explicitly filter the joined table if it's cross-tenant by design

I prefer option 1—if two tables are related, they usually share a tenant anyway.

Why This Matters

Security shouldn't depend on developer discipline. It should be baked into the framework. SQLAlchemy event listeners move tenant isolation from the "nice to have" checklist to the "physically impossible to bypass" category.

I've used this pattern in CitizenApp for two years. Zero accidental data leaks. Junior developers ship features confidently. Code reviews focus on logic, not "did you remember the tenant filter?"

That's the difference between security theater and actual security.

Tailwind CSS Dark Mode Toggle in React 19: Persisting User Preference Without Flash-of-Wrong-Theme on Hydration

Ugur Aslim — Sun, 07 Jun 2026 17:52:01 +0000

Tailwind CSS Dark Mode Toggle in React 19: Persisting User Preference Without Flash-of-Wrong-Theme on Hydration

Dark mode toggles sound trivial until you ship them to production and watch users squint as a white screen flashes across their face for 200ms before the correct theme loads. I've shipped this wrong three times—twice by overthinking it, once by underthinking it.

The problem isn't React or Tailwind. It's execution order. Your JavaScript runs after the browser paints the initial HTML. If that HTML defaults to light mode and your user prefers dark, they see light mode first, then dark mode pops in. Users hate this subtle flicker. It feels broken.

I'm sharing the production-ready solution from CitizenApp that eliminates this flicker entirely using a dead-simple trick: run a tiny script before React hydration even starts.

Why This Matters More Than You Think

When you build a React app with Tailwind, here's what happens on first load:

Browser downloads HTML
Browser downloads CSS (Tailwind stylesheet)
Browser paints initial HTML with CSS applied
Browser downloads JavaScript
React hydrates and your dark mode logic runs

If you put theme logic inside a React component or effect, you're starting in step 5. Your user has already seen the wrong theme in step 3.

The flash-of-wrong-theme (FOUT) is a UX death by a thousand cuts. Most users won't consciously notice it, but they'll feel the site is "janky." It's the difference between a $50/month SaaS and a $500/month SaaS in perceived quality.

I prefer solving this with inline script injection because it's:

Predictable: Runs before React, guaranteed
Lightweight: ~400 bytes of code
Framework-agnostic: Works with any setup
No hydration mismatches: The DOM already matches the correct theme

The Solution: Inline Script + localStorage + Tailwind Classes

Here's the exact implementation from CitizenApp:

1. The Pre-Hydration Script

Drop this into your root HTML template (Astro, Next.js, etc.) in the <head> tag, before any CSS or React:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your App</title>

    <!-- CRITICAL: Run before Tailwind CSS paints -->
    <script>
        (function() {
            const stored = localStorage.getItem('theme');
            const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
            const isDark = stored ? stored === 'dark' : prefersDark;

            if (isDark) {
                document.documentElement.classList.add('dark');
            } else {
                document.documentElement.classList.remove('dark');
            }
        })();
    </script>

    <!-- Tailwind CSS -->
    <link rel="stylesheet" href="/styles.css">
</head>
<body>
    <div id="root"></div>
    <!-- React loads after body content -->
</body>
</html>

Why this works:

IIFE execution: No dependencies, runs synchronously
Placement: Before CSS means the dark class is set before Tailwind applies theme colors
localStorage check: Respects user's previous choice
System preference fallback: If no preference stored, uses prefers-color-scheme

2. React Component for Toggle

Now your React component can safely assume the DOM is already correct:

'use client'; // or 'use strict' in Astro

import { useEffect, useState } from 'react';

export function ThemeToggle() {
    const [isDark, setIsDark] = useState(false);
    const [mounted, setMounted] = useState(false);

    // Hydration safety: only render after mount
    useEffect(() => {
        setMounted(true);
        setIsDark(document.documentElement.classList.contains('dark'));
    }, []);

    if (!mounted) return null;

    const toggle = () => {
        const newIsDark = !isDark;
        setIsDark(newIsDark);

        // Update DOM
        if (newIsDark) {
            document.documentElement.classList.add('dark');
        } else {
            document.documentElement.classList.remove('dark');
        }

        // Persist preference
        localStorage.setItem('theme', newIsDark ? 'dark' : 'light');
    };

    return (
        <button
            onClick={toggle}
            className="p-2 rounded-lg bg-gray-200 dark:bg-gray-800 text-gray-800 dark:text-gray-200"
            aria-label="Toggle theme"
        >
            {isDark ? '☀️' : '🌙'}
        </button>
    );
}

Key decisions:

mounted state: Prevents hydration mismatch (React thinks DOM is dark, but client side hasn't hydrated yet)
Direct DOM manipulation: We're controlling a global state, so classList is cleaner than context for this use case
Synchronous localStorage: Safe because it's a toggle, not a render-blocking operation

3. Tailwind Configuration

Ensure Tailwind is configured to use the class strategy:

// tailwind.config.js
export default {
    darkMode: 'class', // NOT 'media'
    theme: {
        extend: {},
    },
    plugins: [],
};

Why class and not media? Because media respects system preference only—you can't override it with a toggle. class gives you full control.

Alternative: Context + Custom Hook (Overkill Most of the Time)

If you prefer React patterns, here's a hook-based approach for CitizenApp's settings page:

import { createContext, useContext, useEffect, useState } from 'react';

const ThemeContext = createContext<{
    isDark: boolean;
    toggle: () => void;
}>({ isDark: false, toggle: () => {} });

export function ThemeProvider({ children }: { children: React.ReactNode }) {
    const [isDark, setIsDark] = useState(false);
    const [mounted, setMounted] = useState(false);

    useEffect(() => {
        setMounted(true);
        setIsDark(document.documentElement.classList.contains('dark'));
    }, []);

    const toggle = () => {
        const newIsDark = !isDark;
        setIsDark(newIsDark);
        document.documentElement.classList.toggle('dark', newIsDark);
        localStorage.setItem('theme', newIsDark ? 'dark' : 'light');
    };

    if (!mounted) return children; // Avoid hydration mismatch

    return (
        <ThemeContext.Provider value={{ isDark, toggle }}>
            {children}
        </ThemeContext.Provider>
    );
}

export const useTheme = () => useContext(ThemeContext);

I prefer the simple button component in most cases. Context adds abstraction without benefit here.

Gotcha: System Preference Changes Mid-Session

This one burned me when a user toggled their OS dark mode and expected the app to follow. My inline script only runs once.

Fix: Listen for system preference changes:

useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleChange = (e: MediaQueryListEvent) => {
        const stored = localStorage.getItem('theme');
        if (!stored) { // Only auto-sync if user hasn't set preference
            const newIsDark = e.matches;
            setIsDark(newIsDark);
            document.documentElement.classList.toggle('dark', newIsDark);
        }
    };

    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
}, []);

What I Missed (And You Might Too)

The flash still happens if you don't inline the script. Loading it as an external file defeats the purpose because the browser won't execute it until after it downloads and parses. Keep it inline in the <head>.

Also, don't overthink localStorage + context. For a toggle, DOM classes + localStorage are sufficient. I wasted a week on context architecture for what should've been 20 lines of code.

Ship It

That's the entire pattern. No libraries, no magic, no flicker. On CitizenApp, we measure page paint timing and user feedback—this approach sits at 100ms paint time with zero dark mode complaints.

Test it: disable JavaScript, load the page with dark mode preferred. The theme should still be correct (because the inline script ran). Re-enable JavaScript and toggle. Works instantly.

This is a small detail, but small details are what separate production apps from hobby projects.

React 19 Form Actions with FastAPI: Server-Side Validation That Hydrates Client State Without Duplicate Logic

Ugur Aslim — Sun, 07 Jun 2026 08:20:47 +0000

React 19 Form Actions with FastAPI: Server-Side Validation That Hydrates Client State Without Duplicate Logic

Form validation is where I watch developers waste the most time. You write a schema in Pydantic. You duplicate it in Zod on the frontend. You write error messages twice. You wire up loading states manually. You debug why the client and server disagree about what's valid.

I've shipped enough forms to know: this is insane.

React 19's form actions paired with FastAPI give you a path out. Your validation lives once—on the server. Your form component receives structured errors and auto-populates without fetching. Your loading state is built-in. Your action handler runs server-side, so sensitive operations never touch the browser.

This is the pattern I use in CitizenApp, and it's cut our form code by roughly half.

The Old Way (What You're Probably Doing)

Before I show you the good stuff, let me paint the wasteful picture:

Pydantic schema defines validation rules
Zod schema duplicates those rules on the frontend
REST endpoint returns validation errors
useState wires up error messages manually
useTransition handles loading state
useCallback manages submission

That's five places where form logic lives. When you add a validation rule, you update at least three of them.

Worse: if your client-side validation passes but the server rejects it, your UX breaks. Users see a spinner, then a generic error, then they don't know what to fix.

React 19 Form Actions + FastAPI: The Pattern

React 19 gives you useActionState. It's built for server actions—but you can bend it toward FastAPI.

Here's how it works:

Form submits to a server action (a function marked 'use server')
That function calls your FastAPI endpoint
FastAPI returns structured validation errors
React automatically re-renders with those errors populated
No manual state management, no duplicate validation logic

Let me show you the code.

Step 1: Define Your FastAPI Schema (Single Source of Truth)

# backend/schemas.py
from pydantic import BaseModel, EmailStr, Field

class CreateUserRequest(BaseModel):
    email: EmailStr
    name: str = Field(..., min_length=2, max_length=100)
    password: str = Field(..., min_length=12)

class ValidationError(BaseModel):
    field: str
    message: str

class CreateUserResponse(BaseModel):
    success: bool
    user_id: str | None = None
    errors: list[ValidationError] = []

Notice: I'm not writing validation rules anywhere else. Pydantic handles it all.

Step 2: Write Your FastAPI Endpoint

# backend/main.py
from fastapi import FastAPI, HTTPException
from pydantic import ValidationError as PydanticValidationError
import httpx

app = FastAPI()

@app.post("/api/users")
async def create_user(req: CreateUserRequest):
    """
    FastAPI automatically validates the request body against CreateUserRequest.
    If validation fails, it returns a 422 with structured errors.
    """
    # Your business logic here
    # (check if email exists, hash password, etc.)

    try:
        user = await db.users.create(
            email=req.email,
            name=req.name,
            password_hash=hash_password(req.password)
        )
        return CreateUserResponse(success=True, user_id=user.id)
    except Exception as e:
        return CreateUserResponse(
            success=False,
            errors=[
                ValidationError(
                    field="email",
                    message="This email is already registered"
                )
            ]
        )

Key point: FastAPI handles validation. If the request body doesn't match the schema, it responds with 422 and a detailed error. We just need to catch it on the client.

Step 3: Create a Server Action That Calls FastAPI

This is where it gets interesting. Your Next.js (or Astro with a Node adapter) server action becomes a thin bridge:

// app/actions/create-user.ts
'use server'

import { CreateUserRequest, CreateUserResponse, ValidationError } from '@/types'

export async function createUserAction(
  _prevState: CreateUserResponse | null,
  formData: FormData
): Promise<CreateUserResponse> {
  const email = formData.get('email')
  const name = formData.get('name')
  const password = formData.get('password')

  const req: CreateUserRequest = {
    email: email as string,
    name: name as string,
    password: password as string,
  }

  try {
    const response = await fetch(
      `${process.env.FASTAPI_URL}/api/users`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(req),
      }
    )

    if (!response.ok) {
      // FastAPI returns 422 with Pydantic errors
      const errorData = await response.json()

      // Transform Pydantic's error format into our schema
      const errors: ValidationError[] = (errorData.detail || []).map(
        (err: any) => ({
          field: err.loc[1] || 'unknown', // Pydantic error format
          message: err.msg,
        })
      )

      return { success: false, errors, user_id: null }
    }

    return await response.json()
  } catch (error) {
    return {
      success: false,
      user_id: null,
      errors: [{ field: 'form', message: 'Network error. Try again.' }],
    }
  }
}

Step 4: Wire It Up in React with useActionState

// app/components/SignupForm.tsx
'use client'

import { useActionState } from 'react'
import { createUserAction } from '@/app/actions/create-user'

export function SignupForm() {
  const [state, formAction, isPending] = useActionState(
    createUserAction,
    null
  )

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          name="email"
          type="email"
          required
          className="mt-1 block w-full rounded border border-gray-300 px-3 py-2"
        />
        {state?.errors
          ?.filter((e) => e.field === 'email')
          .map((error) => (
            <p key={error.field} className="mt-1 text-sm text-red-600">
              {error.message}
            </p>
          ))}
      </div>

      <div>
        <label htmlFor="name" className="block text-sm font-medium">
          Full Name
        </label>
        <input
          id="name"
          name="name"
          type="text"
          required
          className="mt-1 block w-full rounded border border-gray-300 px-3 py-2"
        />
        {state?.errors
          ?.filter((e) => e.field === 'name')
          .map((error) => (
            <p key={error.field} className="mt-1 text-sm text-red-600">
              {error.message}
            </p>
          ))}
      </div>

      <div>
        <label htmlFor="password" className="block text-sm font-medium">
          Password
        </label>
        <input
          id="password"
          name="password"
          type="password"
          required
          className="mt-1 block w-full rounded border border-gray-300 px-3 py-2"
        />
        {state?.errors
          ?.filter((e) => e.field === 'password')
          .map((error) => (
            <p key={error.field} className="mt-1 text-sm text-red-600">
              {error.message}
            </p>
          ))}
      </div>

      <button
        type="submit"
        disabled={isPending}
        className="w-full rounded bg-blue-600 px-4 py-2 text-white disabled:opacity-50"
      >
        {isPending ? 'Creating...' : 'Sign Up'}
      </button>

      {state?.success && (
        <p className="text-sm text-green-600">
          Account created! User ID: {state.user_id}
        </p>
      )}
    </form>
  )
}

Why This Pattern Works

Single source of truth: Pydantic schema is authoritative. Change it once, and FastAPI validates automatically.

No client-side validation library: You don't need Zod, React Hook Form, or custom validation. The server tells you what's wrong.

Type safety without duplication: Your TypeScript types mirror Pydantic. Generate them once with tools like datamodel-code-generator.

Built-in loading state: useActionState gives you isPending for free. No useState needed.

Structured errors: You get field-level errors, not a generic "validation failed" message. Users know exactly what to fix.

Gotcha: Pydantic Error Format

FastAPI's 422 response doesn't match a clean schema—it returns detail with Pydantic's internal error format:

{
  "detail": [
    {
      "type": "value_error.email",
      "loc": ["body", "email"],
      "msg": "invalid email format",
      "input": "notanemail"
    }
  ]
}

I spent an hour debugging why my error transform wasn't working until I realized loc is a tuple, and the field name is at index 1, not 0. The code above handles it, but it's worth understanding why.

Also: if you need custom validation messages, Pydantic's `Field(description

TypeScript Path Aliases Across Monorepo Workspaces: Configuring tsconfig So Your Astro, React, and FastAPI Projects Share Types Without Import Hell

Ugur Aslim — Sun, 07 Jun 2026 08:20:37 +0000

TypeScript Path Aliases Across Monorepo Workspaces: Configuring tsconfig So Your Astro, React, and FastAPI Projects Share Types Without Import Hell

Monorepos are great until they're not. I've been burned by relative import chains more times than I'd like to admit. You're three directories deep in your React dashboard, you need a User type from your shared package, and you're staring at ../../../packages/types/src/user.ts. Then someone reorganizes the folder structure, and everything breaks.

I'm here to tell you: this problem is solvable with proper TypeScript path alias configuration. I've set this up across CitizenApp's stack—Astro marketing site, React 19 dashboard, FastAPI backend, and shared types package—and I'm going to show you exactly what works.

Why Path Aliases Matter in Monorepos

When you're working with multiple workspaces that need to share types, you have three options:

Relative imports: import { User } from '../../../packages/types'
Published npm packages: Overkill for internal monorepo code
TypeScript path aliases: The Goldilocks solution

Path aliases give you:

Readable imports: import { User } from '@shared/types' instead of relative hell
IDE intellisense: Your editor knows what you're importing
Refactoring safety: Move a file, IDE updates imports automatically
Monorepo clarity: It's obvious code is coming from a shared package, not adjacent directories

The catch? TypeScript doesn't magically know where @shared/types lives across workspace boundaries. You need to configure it properly.

The Monorepo Structure I Use

Here's what CitizenApp looks like:

monorepo/
├── packages/
│   └── types/
│       ├── package.json
│       └── src/
│           ├── user.ts
│           ├── tenant.ts
│           └── index.ts
├── apps/
│   ├── web/
│   │   ├── package.json (Astro)
│   │   └── tsconfig.json
│   ├── dashboard/
│   │   ├── package.json (React 19)
│   │   └── tsconfig.json
│   └── api/
│       └── (FastAPI—more on this later)
├── package.json (root)
└── tsconfig.json (root)

This structure is intentional. Shared types live in packages/types. Applications reference it via path aliases.

Step 1: Configure the Shared Types Package

First, your packages/types/tsconfig.json should be minimal but explicit:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

And packages/types/package.json:

{
  "name": "@shared/types",
  "version": "1.0.0",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"]
}

The exports field is crucial. It tells consumers exactly where to find types. No ambiguity.

Step 2: Root tsconfig.json with Workspace References

Here's your root tsconfig.json—this ties everything together:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["packages/*/src"]
    }
  },
  "ts.Node": {
    "transpileOnly": true,
    "compilerOptions": {
      "module": "commonjs"
    }
  },
  "references": [
    { "path": "packages/types" },
    { "path": "apps/web" },
    { "path": "apps/dashboard" }
  ]
}

Why "references"? They tell TypeScript these are separate compilation units. Each workspace compiles independently, but they know about each other. This prevents circular dependencies and keeps incremental builds fast.

Why "baseUrl" and "paths"? This is where the magic happens. "@shared/*": ["packages/*/src"] means:

Import @shared/types → resolve to packages/types/src
Import @shared/constants → resolve to packages/constants/src

Step 3: Application-Level tsconfig Files

Now, each application extends the root config with its own adjustments.

React Dashboard (apps/dashboard/tsconfig.json):

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src"],
  "references": [{ "path": "../../packages/types" }]
}

Astro Site (apps/web/tsconfig.json):

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "preserve",
    "moduleResolution": "bundler"
  },
  "include": ["src"],
  "references": [{ "path": "../../packages/types" }]
}

Each extends the root, inheriting path aliases. The "references" field in each app ensures TypeScript knows about the types package.

Using It: The Actual Imports

Now you can import in your React component:

// apps/dashboard/src/components/UserCard.tsx
import { User, Tenant } from '@shared/types';

interface Props {
  user: User;
  tenant: Tenant;
}

export function UserCard({ user, tenant }: Props) {
  return (
    <div>
      <h2>{user.email}</h2>
      <p>Tenant: {tenant.name}</p>
    </div>
  );
}

In your Astro page:

// apps/web/src/pages/index.astro
---
import { User } from '@shared/types';

const user: User = {
  id: '123',
  email: 'user@example.com',
};
---

<h1>Welcome, {user.email}</h1>

No ../../../ chains. No duplicate type definitions. Your IDE autocompletes. Builds work.

What About FastAPI?

I'll be direct: Python doesn't use TypeScript path aliases. But here's what I do: I generate Python types from my TypeScript definitions using datamodel-code-generator or pydantic schema exports. The shared source of truth remains the TypeScript types package, and Python consumes generated .py files.

Keep the types in one place, generate outward.

Gotcha: Build Order and Workspace Dependencies

This burned me: if your applications import from @shared/types, make sure packages/types is compiled first. With Turborepo or pnpm workspaces, add this to your root package.json:

{
  "workspaces": ["packages/*", "apps/*"]
}

And in each app's package.json:

{
  "dependencies": {
    "@shared/types": "workspace:*"
  }
}

The workspace:* protocol tells the monorepo tool to link locally, not fetch from npm. Without this, your builds fail silently with "cannot find module" errors.

Another Gotcha: moduleResolution Must Match

I spent two hours debugging why Vercel builds worked but local builds didn't. The issue? My local tsconfig used "nodeNext" while my build system used "bundler". TypeScript resolved paths differently.

Use "bundler" for modern monorepos. It's more predictable.

The Real Win

Once this is set up, your team stops fighting import paths. You can refactor the monorepo structure without updating hundreds of import statements. New team members see @shared/types and instantly understand "oh, that's shared code."

It's a small thing that compounds into massive productivity gains. Worth the 30 minutes to configure correctly.

Anthropic Batch API for Asynchronous Multi-Tenant AI Processing: Cutting Claude Costs by 50% Without Sacrificing Feature Responsiveness

Ugur Aslim — Sat, 06 Jun 2026 08:47:58 +0000

Anthropic Batch API for Asynchronous Multi-Tenant AI Processing: Cutting Claude Costs by 50% Without Sacrificing Feature Responsiveness

I'm going to be blunt: if you're running a SaaS that uses Claude, and you haven't implemented the Batch API yet, you're hemorrhaging money. Not metaphorically—literally 50% off the per-token cost for any request that doesn't need a response in the next 60 seconds.

At CitizenApp, we process thousands of document summaries, compliance classifications, and policy analyses daily. Our first instinct was synchronous: user uploads document → Claude responds in real-time → dashboard updates. It felt responsive. It also felt like burning cash.

Then we realized: 80% of those requests don't actually need synchronous responses. A user uploads a document for summarization? They're fine waiting 5–30 minutes. A tenant wants to bulk-classify 500 policies? That's explicitly an async job. The Batch API is built for this, and it's absurdly underutilized.

Here's how I wired it into CitizenApp—and why you should too.

Why Batch API Matters (Beyond the 50% Discount)

The 50% cost reduction is the headline, but the real win is architectural. Batching forces you to separate concerns:

Synchronous requests (fast, expensive): Real-time chat, document Q&A, immediate feedback loops.
Asynchronous requests (slow, cheap): Bulk operations, scheduled analyses, background enrichment.

This separation is healthy. You stop cramming everything through Claude's sync API and actually think about what needs to be urgent.

In CitizenApp's case, we reduced our monthly Claude bill from ~$8k to ~$4k while actually increasing feature coverage. The key was offloading 65% of our workload to batches.

Architecture: Queue → Batch → LISTEN/NOTIFY → React

Here's the flow:

User Request
    ↓
FastAPI Endpoint (Validate, Enqueue)
    ↓
PostgreSQL Queue Table
    ↓
Batch Processor (reads queue, submits to Anthropic)
    ↓
Anthropic Batch Job (runs in background)
    ↓
Webhook/Polling Handler (gets results)
    ↓
PostgreSQL LISTEN/NOTIFY
    ↓
WebSocket → React 19 Dashboard (real-time update)

Let's build it.

Step 1: Data Model

# models.py
from sqlalchemy import Column, String, Integer, Text, DateTime, Enum, ForeignKey
from sqlalchemy.orm import declarative_base
from datetime import datetime
import enum

Base = declarative_base()

class AIJobStatus(str, enum.Enum):
    QUEUED = "queued"
    SUBMITTED = "submitted"
    PROCESSING = "processing"
    COMPLETED = "completed"
    FAILED = "failed"

class AIJob(Base):
    __tablename__ = "ai_jobs"

    id = Column(String, primary_key=True)
    tenant_id = Column(String, ForeignKey("tenants.id"), nullable=False, index=True)
    user_id = Column(String, nullable=False)
    job_type = Column(String, nullable=False)  # "summarize", "classify", etc.

    status = Column(Enum(AIJobStatus), default=AIJobStatus.QUEUED, index=True)

    input_data = Column(Text, nullable=False)  # JSON stringified
    result = Column(Text, nullable=True)  # Result from Claude

    batch_id = Column(String, nullable=True, index=True)  # Anthropic batch ID
    request_id = Column(String, nullable=True)  # Within batch

    created_at = Column(DateTime, default=datetime.utcnow, index=True)
    completed_at = Column(DateTime, nullable=True)

    error_message = Column(Text, nullable=True)

Step 2: Queue Endpoint

# api/ai.py
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel
import uuid
import json
from sqlalchemy.orm import Session
from database import get_db
from models import AIJob, AIJobStatus

router = APIRouter()

class SummarizeRequest(BaseModel):
    document_text: str
    max_length: int = 500

@router.post("/api/ai/summarize")
async def queue_summarize(
    request: SummarizeRequest,
    db: Session = Depends(get_db),
    tenant_id: str = Depends(get_tenant_id),
    user_id: str = Depends(get_user_id),
):
    """
    Queue a document for summarization (async).
    Returns immediately with job ID.
    User receives result via WebSocket when batch completes.
    """

    job_id = str(uuid.uuid4())

    job = AIJob(
        id=job_id,
        tenant_id=tenant_id,
        user_id=user_id,
        job_type="summarize",
        input_data=json.dumps({
            "document_text": request.document_text,
            "max_length": request.max_length,
        }),
        status=AIJobStatus.QUEUED,
    )

    db.add(job)
    db.commit()

    return {
        "job_id": job_id,
        "status": "queued",
        "message": "Your request is queued. You'll receive results in 5-30 minutes.",
    }

Step 3: Batch Processor (Background Task)

I prefer a separate worker process (via Celery or APScheduler) that runs periodically. Here's APScheduler for simplicity:


python
# workers/batch_processor.py
from anthropic import Anthropic
from sqlalchemy.orm import Session
from database import SessionLocal
from models import AIJob, AIJobStatus
import json
from datetime import datetime

client = Anthropic()

def process_batch_jobs():
    """
    Run every 5 minutes (via APScheduler).
    Collects queued jobs and submits to Anthropic Batch API.
    """
    db = SessionLocal()

    # Get all queued jobs (batch size: 10k requests per batch max)
    queued_jobs = db.query(AIJob).filter(
        AIJob.status == AIJobStatus.QUEUED
    ).limit(100).all()

    if not queued_jobs:
        db.close()
        return

    # Build batch request
    requests = []
    job_map = {}

    for job in queued_jobs:
        input_data = json.loads(job.input_data)

        if job.job_type == "summarize":
            message = f"Summarize the following document in {input_data['max_length']} words:\n\n{input_data['document_text']}"
        elif job.job_type == "classify":
            message = f"Classify this text into one of: {input_data['categories']}\n\nText: {input_data['text']}"
        else:
            continue

        request_id = job.id
        job_map[request_id] = job.id

        requests.append({
            "custom_id": request_id,
            "params": {
                "model": "claude-3-5-sonnet-20241022",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": message}],
            },
        })

    # Submit batch to Anthropic
    batch = client.beta.messages.batches.create(
        requests=requests,
        betas=["batch-2024-09-24"],
    )

    # Mark all jobs as submitted
    for job in queued_jobs:
        job.status = AIJobStatus.SUBMITTED
        job.batch_id = batch.id

    db.commit()
    print(f"Submitted batch {batch.id} with {len(requests)} requests")
    db.close()


def poll_batch_results():
    """
    Run every 30 seconds.
    Checks submitted batches for completion, stores results.
    """
    db = SessionLocal()

    # Get all submitted jobs
    submitted_jobs = db.query(AIJob).filter(
        AIJob.status == AIJobStatus.SUBMITTED
    ).all()

    batch_ids = set(job.batch_id for job in submitted_jobs)

    for batch_id in batch_ids:
        batch = client.beta.messages.batches.retrieve(batch_id, betas=["batch-2024-09-24"])

        if batch.processing_status == "in_progress":
            continue

        if batch.processing_status == "expired":
            # Mark jobs as failed
            for job in submitted_jobs:
                if job.batch_id == batch_id:
                    job.status = AIJobStatus.FAILED
                    job.error_message = "Batch expired"
            db.commit()
            continue

        # Batch complete — fetch results
        results = client.beta.messages.batches.results(batch_id, betas=["batch-2024-09-24"])

        for result in results:
            request_id = result.custom_id
            job = db.query(AIJob).filter(AIJob.id == request_id).first()

            if not job:
                continue

            if result.result.type == "succeeded":
                job.status = AIJobStatus.COMPLETED
                job.result = result.result.message.content[0].text
            elif result.result.type == "errored":
                job.status = AIJobStatus.FAILED
                job.error_message = result.result.error.message

            job.completed_at = datetime.utcnow()

        db.commit()
        # Notify connected clients (next step)
        notify_clients_batch_complete(batch_id)

    db.close()

React 19 useActionState for Form-Driven AI Features: Building Progressive Enhancement Without JavaScript Frameworks Complexity

Ugur Aslim — Sat, 06 Jun 2026 08:47:49 +0000

React 19 useActionState for Form-Driven AI Features: Building Progressive Enhancement Without JavaScript Frameworks Complexity

I've built nine AI features in CitizenApp, and I can tell you with certainty: most of them started as a tangled mess of useState hooks managing loading states, error states, and async operations simultaneously. The breaking point came when I realized I was writing the same form state machine over and over—loading spinner, validation errors, success message, then back to idle. That's when I discovered useActionState in React 19, and it changed how I approach form-driven AI features.

Here's the thing: useActionState isn't just syntactic sugar. It fundamentally shifts your mental model from "manage component state, then handle side effects" to "declare what happens when the form submits." For AI features especially—where you're waiting on Claude API responses and need to show progressive feedback—this is exactly what you need.

Why useActionState, Not useState + useEffect?

The traditional pattern looks like this:

const [input, setInput] = useState('');
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [result, setResult] = useState<string | null>(null);

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

  try {
    const response = await fetch('/api/analyze', {
      method: 'POST',
      body: JSON.stringify({ text: input })
    });

    if (!response.ok) throw new Error('API failed');
    const data = await response.json();
    setResult(data.analysis);
  } catch (err) {
    setError(err instanceof Error ? err.message : 'Unknown error');
  } finally {
    setLoading(false);
  }
};

This works, but you're manually orchestrating four separate state updates. Race conditions hide in there. The form is uncontrolled by the server. Validation errors from Claude get mixed with network errors. By the time you add optimistic updates, you've got spaghetti.

With useActionState, you declare the action once and bind it directly to the form:

const [state, formAction, isPending] = useActionState(
  async (prevState, formData) => {
    const text = formData.get('text') as string;

    if (!text.trim()) {
      return { error: 'Text cannot be empty', data: null };
    }

    try {
      const response = await fetch('/api/analyze', {
        method: 'POST',
        body: JSON.stringify({ text })
      });

      if (!response.ok) {
        return { error: 'Analysis failed', data: null };
      }

      const data = await response.json();
      return { error: null, data: data.analysis };
    } catch (err) {
      return { 
        error: err instanceof Error ? err.message : 'Unknown error',
        data: null 
      };
    }
  },
  { error: null, data: null }
);

Notice what's gone: no setLoading, no setError, no manual event handling. The form submission is implicit. isPending is automatic. Validation and async logic live in the same function.

Building an AI Feature with useActionState

Let me show you a real pattern from CitizenApp. We have a feature that analyzes user feedback using Claude. Here's the component:

'use client';

import { useActionState } from 'react';

interface AnalysisState {
  error: string | null;
  analysis: string | null;
  tokenUsage?: { input: number; output: number };
}

async function analyzeFeedback(
  _prevState: AnalysisState,
  formData: FormData
): Promise<AnalysisState> {
  const feedback = formData.get('feedback') as string;
  const sentiment = formData.get('sentiment') as string;

  // Validation
  if (!feedback.trim() || feedback.length < 10) {
    return {
      error: 'Feedback must be at least 10 characters',
      analysis: null
    };
  }

  if (!['positive', 'negative', 'neutral'].includes(sentiment)) {
    return {
      error: 'Invalid sentiment selection',
      analysis: null
    };
  }

  try {
    // Call our backend which speaks to Claude
    const response = await fetch('/api/analyze-feedback', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ feedback, sentiment })
    });

    if (!response.ok) {
      const errData = await response.json();
      return {
        error: errData.message || 'Analysis failed',
        analysis: null
      };
    }

    const { analysis, tokenUsage } = await response.json();
    return {
      error: null,
      analysis,
      tokenUsage
    };
  } catch (err) {
    return {
      error: 'Network error. Please try again.',
      analysis: null
    };
  }
}

export function FeedbackAnalyzer() {
  const [state, formAction, isPending] = useActionState(
    analyzeFeedback,
    { error: null, analysis: null }
  );

  return (
    <div className="max-w-2xl mx-auto p-6">
      <form action={formAction} className="space-y-4">
        <div>
          <label className="block text-sm font-medium mb-2">
            Your Feedback
          </label>
          <textarea
            name="feedback"
            className="w-full p-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
            placeholder="Tell us what you think..."
            disabled={isPending}
          />
        </div>

        <div>
          <label className="block text-sm font-medium mb-2">
            Overall Sentiment
          </label>
          <select
            name="sentiment"
            className="w-full p-3 border border-gray-300 rounded-lg"
            disabled={isPending}
          >
            <option value="">Select sentiment...</option>
            <option value="positive">Positive</option>
            <option value="negative">Negative</option>
            <option value="neutral">Neutral</option>
          </select>
        </div>

        <button
          type="submit"
          disabled={isPending}
          className="w-full bg-blue-600 text-white py-2 rounded-lg disabled:opacity-50"
        >
          {isPending ? 'Analyzing...' : 'Analyze with Claude'}
        </button>
      </form>

      {state.error && (
        <div className="mt-4 p-4 bg-red-50 border border-red-200 rounded-lg">
          <p className="text-red-800">{state.error}</p>
        </div>
      )}

      {state.analysis && (
        <div className="mt-4 p-4 bg-green-50 border border-green-200 rounded-lg">
          <p className="text-green-900">{state.analysis}</p>
          {state.tokenUsage && (
            <p className="text-xs text-green-700 mt-2">
              Used {state.tokenUsage.input} input + {state.tokenUsage.output} output tokens
            </p>
          )}
        </div>
      )}
    </div>
  );
}

The backend (FastAPI) is straightforward:

from fastapi import FastAPI, HTTPException
import anthropic

app = FastAPI()

@app.post("/api/analyze-feedback")
async def analyze_feedback(request: dict):
    feedback = request.get("feedback", "").strip()
    sentiment = request.get("sentiment", "").strip()

    if not feedback or len(feedback) < 10:
        raise HTTPException(status_code=400, detail="Feedback too short")

    if sentiment not in ["positive", "negative", "neutral"]:
        raise HTTPException(status_code=400, detail="Invalid sentiment")

    client = anthropic.Anthropic()

    try:
        message = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=500,
            messages=[
                {
                    "role": "user",
                    "content": f"Analyze this {sentiment} feedback and provide 2-3 actionable insights:\n\n{feedback}"
                }
            ]
        )

        return {
            "analysis": message.content[0].text,
            "tokenUsage": {
                "input": message.usage.input_tokens,
                "output": message.usage.output_tokens
            }
        }
    except anthropic.APIError as e:
        raise HTTPException(status_code=500, detail=str(e))

The Real Win: Semantic HTML and Progressive Enhancement

Here's why I prefer useActionState over Next.js Server Actions for this pattern: it works as regular form submission even without JavaScript. Your semantic HTML works. The disabled attributes prevent double-submission. If you're using Astro with islands architecture or just React on its own, you're not locked into a full-stack framework.

The form will submit, the server will process it, and if JavaScript fails to load, your users still get an error message or a page reload. That's resilience.

What I Missed the First Time

The gotcha: useActionState doesn't clear the form automatically. If you want to reset inputs after successful submission, you need to either:

Render a success message instead of the form
Use a ref to manually reset the form
Return a new form state that tracks submission ID and re-render conditionally

I initially expected it to be like form libraries, but it's simpler—intentionally. It's a state machine, not form magic.

Also: the `