DEV Community: Ugur Aslim

Tailwind CSS Just-In-Time Compilation in Monorepos: Why Your Build Times Explode With Shared Component

Ugur Aslim — Wed, 12 Aug 2026 10:52:03 +0000

Tailwind CSS Just-In-Time Compilation in Monorepos: Why Your Build Times Explode With Shared Components

I built CitizenApp as a monorepo with 6 internal packages—a core UI library, feature modules, and admin dashboards. Everything ran fine until we hit 50+ shared components. Then our Tailwind build went from 2 seconds to 45 seconds. That's not a typo. Forty-five seconds for a dev rebuild because the JIT compiler was re-scanning the entire monorepo on every change.

The problem isn't Tailwind. It's how you configure content paths in a monorepo. I've made every mistake here, and I'm going to show you exactly how to avoid them.

The Core Problem: Content Path Explosion

Tailwind's JIT compiler needs to know where your templates live. In a monorepo, you have content in multiple places:

packages/
  ui-library/src/components/Button.tsx
  features/dashboard/src/pages/index.tsx
  admin/src/layouts/AdminLayout.tsx

The naive approach is what I did initially:

// tailwind.config.js - THE WRONG WAY
export default {
  content: [
    './src/**/*.{ts,tsx}',
    '../ui-library/src/**/*.{ts,tsx}',
    '../features/*/src/**/*.{ts,tsx}',
    '../admin/src/**/*.{ts,tsx}',
  ],
  theme: { extend: {} },
  plugins: [],
};

This works, but Tailwind watches every file in every package. When you edit a button in ui-library, the compiler re-scans all 6 packages. When you edit a dashboard page, same thing. Quadratic growth.

I watched the file watcher logs. On a single keystroke in one component, Tailwind was scanning 47,000 files. That's why the build took 45 seconds.

Solution 1: Use Package-Level Config Files

Instead of one global config scanning everything, give each package its own Tailwind config that only knows about itself:

// packages/ui-library/tailwind.config.js
export default {
  content: ['./src/**/*.{ts,tsx}'],
  theme: { extend: {} },
  plugins: [],
};

// packages/features/dashboard/tailwind.config.js
export default {
  content: [
    './src/**/*.{ts,tsx}',
    // ONLY reference what this package needs
    '../ui-library/src/**/*.{ts,tsx}',
  ],
  theme: { extend: {} },
  plugins: [],
};

But here's the catch: you still need a root config for the main app. The trick is making it lazy—only include packages that actually get bundled into your final output.

// apps/web/tailwind.config.js - THE RIGHT WAY
export default {
  content: [
    './src/**/*.{ts,tsx}',
    // Only include packages we ACTUALLY import
    '../../packages/ui-library/src/**/*.{ts,tsx}',
    '../../packages/auth/src/**/*.{ts,tsx}',
    // DO NOT use glob patterns like ../../packages/*/src/**
    // That scans everything, even packages you don't use
  ],
  theme: { extend: {} },
  plugins: [],
};

Why explicit is better: Explicit paths force you to declare dependencies. You can't accidentally slow down your build by adding a new package you don't use.

After this change, our build time dropped to 8 seconds. Still not 5, but getting there.

Solution 2: Pre-Build and Export CSS Classes

The real performance win is not relying on JIT scanning for shared components. Pre-build them.

For ui-library, I create a static CSS output that includes all component utilities:

// packages/ui-library/tailwind.config.js
export default {
  content: [
    './src/**/*.{ts,tsx}',
    // Add a safelist for all component variants we support
    {
      pattern: /Button--(primary|secondary|danger|ghost)/,
      variants: ['hover', 'focus', 'disabled'],
    },
  ],
  theme: {
    extend: {
      colors: {
        primary: '#0066FF',
        secondary: '#666666',
      },
    },
  },
  plugins: [],
};

The safelist tells Tailwind: "Always include these classes, even if you don't find them in the content scan." This prevents JIT from purging utilities that exist as dynamic strings:

// packages/ui-library/src/components/Button.tsx
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
}

export function Button({ variant = 'primary', ...props }: ButtonProps) {
  // Dynamic class names need safelist!
  const variantClass = `Button--${variant}`;
  const baseStyles = 'px-4 py-2 rounded font-semibold transition';

  const variantStyles: Record<string, string> = {
    primary: 'bg-primary text-white hover:bg-blue-700',
    secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
    danger: 'bg-red-600 text-white hover:bg-red-700',
    ghost: 'bg-transparent border border-gray-300 hover:bg-gray-100',
  };

  return (
    <button 
      className={`${baseStyles} ${variantStyles[variant]}`}
      {...props}
    />
  );
}

Then in the root app, reference the pre-built output:

// apps/web/tailwind.config.js
export default {
  content: [
    './src/**/*.{ts,tsx}',
    // Pre-built components are already styled, don't re-scan
    '../../packages/ui-library/dist/**/*.js',
  ],
  theme: { extend: {} },
  plugins: [],
};

This dropped us to 4.2 seconds.

Solution 3: Watch Only Changed Packages

The last trick is smarter file watching. Use Tailwind's watch mode with a filter:

{
  "scripts": {
    "dev": "turbo run dev --filter=@app/web",
    "build": "turbo run build"
  }
}

With Turbo (or Nx), only changed packages trigger rebuilds. Tailwind only watches files in packages that are actually running.

Gotcha: Safelist Bloat

Here's what burned me: I was too aggressive with safelists.

// WRONG - This defeats purging
safelist: [
  {
    pattern: /./,  // matches everything!
    variants: ['hover', 'focus', 'active'],
  }
]

Safelist disables purging for matching patterns. If your pattern is too broad, your CSS bundle explodes. I accidentally included a 340KB stylesheet because I safelisted all utilities with "text-" in them.

The fix: only safelist truly dynamic classes you can't predict:

// RIGHT - Specific and minimal
safelist: [
  // Only component variants that are computed at runtime
  { pattern: /^(Button|Input|Card)--/ },
  // Only colors from your theme that come from API data
  { pattern: /^(text|bg)-(primary|secondary|danger)/ },
]

What I Missed

I initially thought the problem was Tailwind itself being slow. It's not. Tailwind's JIT is incredibly fast—the problem is content path misconfiguration making it scan way more than it should.

Also, I didn't realize that CSS-in-JS libraries (Emotion, styled-components) in shared components break content scanning entirely. If your UI library uses CSS-in-JS, Tailwind can't find the utilities and will purge them. You have to use safelist or pre-built CSS.

The Final Config

Here's what works for CitizenApp's 6-package setup with sub-5-second builds:

// apps/web/tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  content: [
    './src/**/*.{ts,tsx}',
    '../../packages/ui-library/src/**/*.{ts,tsx}',
    '../../packages/auth/src/**/*.{ts,tsx}',
  ],
  theme: {
    extend: {
      colors: { primary: '#0066FF' },
    },
  },
  safelist: [
    { pattern: /^(button|input|card)--/ },
    { pattern: /^(text|bg)-\w+/ },
  ],
} satisfies Config;

Build time: 4.8 seconds on 5 packages with 200+ components.

The key insight: make Tailwind's job smaller, not faster. Explicit content paths, package-level configs, and strategic safelists beat any optimization trick.

TanStack Query Advanced Patterns: Optimistic Updates & Cache Management

Ugur Aslim — Mon, 03 Aug 2026 16:29:30 +0000

TanStack Query Advanced Patterns: Optimistic Updates & Cache Management

Most React developers stop at useQuery and useMutation. They fetch data, show a spinner, handle errors. Ship it. But when you're building CitizenApp with 9 AI features and concurrent user actions, basic patterns crumble. Users see loading states that shouldn't exist. Cache gets stale. Real-time features lag. I've rebuilt our mutation strategy three times. Here's what actually works in production.

Why Optimistic Updates Matter More Than You Think

The difference between a good product and an annoying one is often invisible: perceived latency. When a user submits a form, they expect instant feedback. If you wait for the server, you've already lost them to the spinning wheel.

I learned this the hard way. In CitizenApp's early days, we had users click "Generate AI Response" and stare at loaders for 3–5 seconds while the Claude API processed. Same latency, but with optimistic updates? Users immediately see their action registered. The wait feels less painful because something changed.

Here's the real pattern:

// hooks/useOptimisticMutation.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useUpdateCitizen(citizenId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (updates: Partial<Citizen>) => {
      const res = await fetch(`/api/citizens/${citizenId}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updates),
      });
      if (!res.ok) throw new Error('Update failed');
      return res.json();
    },

    // Optimistic update: update cache BEFORE server responds
    onMutate: async (updates) => {
      // Cancel ongoing queries so they don't overwrite our optimistic data
      await queryClient.cancelQueries({
        queryKey: ['citizen', citizenId],
      });

      // Snapshot old data in case we need to rollback
      const previousCitizen = queryClient.getQueryData<Citizen>([
        'citizen',
        citizenId,
      ]);

      // Immediately update the cache
      queryClient.setQueryData(
        ['citizen', citizenId],
        (old: Citizen) => ({
          ...old,
          ...updates,
        })
      );

      return { previousCitizen };
    },

    // On success, refetch to ensure server truth wins
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: ['citizen', citizenId],
      });
    },

    // On error, rollback to the snapshot
    onError: (err, variables, context) => {
      if (context?.previousCitizen) {
        queryClient.setQueryData(
          ['citizen', citizenId],
          context.previousCitizen
        );
      }
    },
  });
}

This pattern does three things:

Cancels in-flight queries so a stale refetch doesn't overwrite your optimistic data
Snapshots the old state for rollback if things fail
Invalidates after success so you sync with server truth, not just trust your prediction

Use it like this:

export function CitizenForm({ citizenId }: { citizenId: string }) {
  const { data: citizen } = useQuery({
    queryKey: ['citizen', citizenId],
    queryFn: () => fetch(`/api/citizens/${citizenId}`).then(r => r.json()),
  });

  const updateMutation = useUpdateCitizen(citizenId);

  const handleNameChange = (name: string) => {
    updateMutation.mutate({ name });
  };

  return (
    <input
      defaultValue={citizen?.name}
      onChange={(e) => handleNameChange(e.target.value)}
      disabled={updateMutation.isPending}
    />
  );
}

The input updates instantly because setQueryData changes what useQuery returns. No spinner. The server request happens in the background. If it fails, we rollback. If it succeeds, we refetch to catch any server-side calculations (e.g., updated modifiedAt timestamps).

Cache Strategy for Multi-Tenant Apps

Here's where most teams stumble: tenant isolation. If you have multiple workspaces/organizations, mixing cache between them is a security and data-correctness nightmare.

I prefer a scoped cache key strategy:

// lib/queryKeys.ts
export const queryKeys = {
  citizens: (tenantId: string) => [
    'tenants',
    tenantId,
    'citizens',
  ] as const,
  citizen: (tenantId: string, citizenId: string) => [
    'tenants',
    tenantId,
    'citizens',
    citizenId,
  ] as const,
  aiResponses: (tenantId: string, citizenId: string) => [
    'tenants',
    tenantId,
    'citizens',
    citizenId,
    'ai-responses',
  ] as const,
};

This forces you to always scope queries by tenant. If you switch orgs, you invalidate everything:

// hooks/useSwitchTenant.ts
export function useSwitchTenant() {
  const queryClient = useQueryClient();

  return (newTenantId: string) => {
    // Clear all cached data for the old tenant
    queryClient.removeQueries();

    // Or more precisely, remove only the old tenant's data
    queryClient.removeQueries({
      predicate: (query) => {
        const [scope, tenantId] = query.queryKey;
        return scope === 'tenants' && tenantId !== newTenantId;
      },
    });
  };
}

Why? Because I've seen race conditions where users switched orgs, the UI updated, but queries from the old org were still in-flight and overwrote the new org's data. Scoped keys + explicit invalidation prevents that entirely.

Real-Time Sync Without Chaos

The moment you add WebSockets or Server-Sent Events, cache invalidation becomes harder. You can't just invalidateQueries on every server message—you'll thrash.

// hooks/useRealTimeUpdates.ts
export function useRealTimeUpdates(tenantId: string) {
  const queryClient = useQueryClient();

  useEffect(() => {
    const eventSource = new EventSource(
      `/api/tenants/${tenantId}/updates?token=${getToken()}`
    );

    eventSource.addEventListener('citizen-updated', (event) => {
      const { citizenId, changes } = JSON.parse(event.data);

      // Surgical update: only update the specific citizen
      queryClient.setQueryData(
        queryKeys.citizen(tenantId, citizenId),
        (old: Citizen) => ({ ...old, ...changes })
      );

      // If it's a list update, update the list too
      queryClient.setQueryData(
        queryKeys.citizens(tenantId),
        (old: Citizen[]) =>
          old?.map((c) => (c.id === citizenId ? { ...c, ...changes } : c))
      );
    });

    return () => eventSource.close();
  }, [tenantId, queryClient]);
}

Don't invalidate the whole list. Surgically update the specific item. This preserves pagination, sort order, and filters. The UI updates instantly without refetching.

Gotcha: Mutation Lifecycle Timing

Here's what burned me: if you call invalidateQueries in onSuccess and the refetch takes time, users see the optimistic update flicker away briefly while the refetch loads.

// ❌ This causes flicker
onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: ['citizens'] });
}

// ✅ Better: let the mutation result populate the cache directly
onSuccess: (data) => {
  queryClient.setQueryData(
    ['citizen', citizenId],
    data
  );
  // Only invalidate related lists
  queryClient.invalidateQueries({
    queryKey: ['citizens'],
    exact: false,
  });
}

The second approach uses the server response directly, so the cache is already "refreshed" before refetches happen. Less flickering, snappier feel.

What I Missed Early On

I used to think TanStack Query was just a fetch wrapper. It's not. It's a state machine for async data. The real power is the cache layer. Once you grok that mutations should update cache first, not after, everything clicks. Optimistic updates aren't fancy—they're the default way async should work in 2024.

Build your app assuming latency. Users are more forgiving of loading when something already changed.

SQLAlchemy Composite Foreign Keys for Multi-Tenant Hierarchical Permissions: Enforcing (tenant_id, role_id) Constraints

Ugur Aslim — Sat, 01 Aug 2026 08:38:22 +0000

I burned this one hard in CitizenApp's early months. A customer's support team member somehow gained admin access to a completely different tenant's workspace. The bug? We assigned roles using only user_id and role_id, never checking that the role's tenant_id matched the user's tenant_id. The database had no constraint preventing it. Application-level filtering caught 99% of cases, but a race condition during a bulk role migration created that one golden window where the star-alignment permissions leaked across tenant boundaries.

It took three hours of log archaeology to find it. It would have taken three seconds for a composite foreign key constraint to prevent it.

The Problem With Single-Column Foreign Keys in Multi-Tenant Systems

Most developers reach for the obvious schema first:

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey("tenants.id"), nullable=False)

class Role(Base):
    __tablename__ = "roles"
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey("tenants.id"), nullable=False)
    name = Column(String, nullable=False)

class UserRole(Base):
    __tablename__ = "user_roles"
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    role_id = Column(Integer, ForeignKey("roles.id"), nullable=False)

This looks reasonable until you realize: the database doesn't know that user_id and role_id must belong to the same tenant. You're enforcing that constraint in your ORM query logic or middleware. That's a tax on every permission check, and it's a tax developers pay inconsistently.

The fix is composite foreign keys. Instead of trusting application code to filter correctly, make the database enforce it structurally.

Composite Foreign Keys: Database-Level Tenant Isolation

Here's the corrected schema:

from sqlalchemy import ForeignKey, UniqueConstraint, Table, Column, Integer, String, Index
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Tenant(Base):
    __tablename__ = "tenants"
    id = Column(Integer, primary_key=True)
    name = Column(String, nullable=False)

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey("tenants.id"), nullable=False)
    email = Column(String, nullable=False)
    __table_args__ = (
        UniqueConstraint("tenant_id", "email", name="uq_user_tenant_email"),
    )

class Role(Base):
    __tablename__ = "roles"
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey("tenants.id"), nullable=False)
    name = Column(String, nullable=False)
    __table_args__ = (
        UniqueConstraint("tenant_id", "id", name="uq_role_tenant_id"),
    )

class UserRole(Base):
    __tablename__ = "user_roles"
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False, primary_key=True)
    role_id = Column(Integer, nullable=False, primary_key=True)
    tenant_id = Column(Integer, nullable=False, primary_key=True)

    __table_args__ = (
        # Composite FK: enforces role belongs to user's tenant
        ForeignKey(
            ["tenant_id", "role_id"],
            ["roles.tenant_id", "roles.id"],
            name="fk_userrole_role_tenant"
        ),
        # Composite FK: enforces user belongs to this tenant
        ForeignKey(
            ["user_id", "tenant_id"],
            ["users.id", "users.tenant_id"],
            name="fk_userrole_user_tenant"
        ),
    )

The magic is in __table_args__. The first composite FK says: "tenant_id + role_id must exist as a (tenant_id, id) pair in the roles table." The second says: "user_id + tenant_id must match a user in their tenant." Together, they guarantee that a user and their assigned roles live in the same tenant.

Try to insert a cross-tenant assignment:

# Tenant 1 user, Tenant 2 role
from sqlalchemy import create_engine
from sqlalchemy.orm import Session

engine = create_engine("postgresql://...")
Base.metadata.create_all(engine)

with Session(engine) as session:
    # This will FAIL with IntegrityError
    session.execute("""
        INSERT INTO user_roles (user_id, role_id, tenant_id)
        VALUES (1, 999, 2)
    """)
    session.commit()

The database rejects it instantly. No ORM query tricks needed. No race condition window.

Why I Prefer Composite FKs Over Application Filters

Application-level filtering is optional. A junior developer queries user_roles without joining to verify tenant_id. A stored procedure gets written that forgets the filter. A caching layer returns stale data. Filtering happens in the controller, but some service method bypasses it.

Composite constraints are mandatory and testable at the schema level. Every insert, update, and delete that violates the rule fails the same way, in the same place, with the same error. You can validate your schema in tests without touching application code.

def test_composite_fk_prevents_cross_tenant_roles():
    """Verify that assigning a role from tenant B to a user in tenant A fails."""
    from sqlalchemy import text, exc

    with Session(engine) as session:
        # Tenants
        t1 = Tenant(id=1, name="Acme")
        t2 = Tenant(id=2, name="Globex")
        session.add_all([t1, t2])
        session.flush()

        # Users in each tenant
        u1 = User(id=1, tenant_id=1, email="alice@acme.com")
        u2 = User(id=2, tenant_id=2, email="bob@globex.com")
        session.add_all([u1, u2])
        session.flush()

        # Roles in each tenant
        r1 = Role(id=1, tenant_id=1, name="Admin")
        r2 = Role(id=2, tenant_id=2, name="Admin")  # Same name, different tenant
        session.add_all([r1, r2])
        session.flush()

        # Attempt: assign Globex admin role to Acme user
        try:
            session.execute(text("""
                INSERT INTO user_roles (user_id, role_id, tenant_id)
                VALUES (1, 2, 1)
            """))
            session.commit()
            assert False, "Should have raised IntegrityError"
        except exc.IntegrityError:
            pass  # Expected

This test is a schema contract. If someone refactors the foreign key logic and forgets composite constraints, the test fails immediately.

Gotcha: Cascading Deletes and Composite Keys

Here's where I tripped up: if you're tempted to add cascade="all, delete" to make cleanup automatic, understand what happens.

# DON'T do this lightly
class UserRole(Base):
    __tablename__ = "user_roles"

    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        primary_key=True
    )
    role_id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, primary_key=True)

If a user is deleted, all their role assignments cascade-delete automatically. That's good. But when you have composite keys, deleting a tenant doesn't automatically cascade through user_roles—it only cascades from the users and roles tables separately. You might orphan records or create locking issues during bulk deletes.

My preference: Use explicit cascade on the user side only, and handle role orphaning with application-level soft deletes or audit triggers.

class UserRole(Base):
    __tablename__ = "user_roles"
    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        primary_key=True
    )
    role_id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, primary_key=True)

    __table_args__ = (
        ForeignKey(
            ["tenant_id", "role_id"],
            ["roles.tenant_id", "roles.id"],
            name="fk_userrole_role_tenant"
            # ondelete="CASCADE" omitted; roles table deletion handled separately
        ),
    )

What I Missed Early On

I initially thought composite foreign keys were only for legacy systems. I was wrong. They're the foundational defense for any multi-tenant system with role hierarchies. The tiny schema complexity—a few extra columns in join tables—pays dividends in prevented bugs.

If you're building a SaaS with role-based access, do this from day one. Your future self, reviewing logs at 2 AM, will thank you.

PostgreSQL JSON Columns: Flexible Schema Design for Modern Applications

Ugur Aslim — Tue, 28 Jul 2026 09:09:44 +0000

I've built three production SaaS products, and I can tell you with confidence: premature normalization is the silent killer of developer velocity. Your schema shouldn't force you to create seventeen junction tables for features you're still figuring out.

PostgreSQL's JSONB is the antidote—but only if you understand when to use it and how to query it properly. I've watched teams swing between two extremes: pure relational schemas that require migrations every sprint, and schemaless blobs that become impossible to query. The sweet spot is JSONB for semi-structured data with strategic indexing.

Why JSONB Over Regular JSON

PostgreSQL offers two JSON types: json (stores text, re-parses on every query) and jsonb (binary format, indexable, queryable). Use JSONB. Always. The performance difference is night and day, and JSONB supports all the operators you actually need.

I prefer JSONB because it lets me ship features faster without sacrificing queryability. In CitizenApp, user preferences evolved constantly—we added dark mode, notification settings, feature flags, timezone overrides. Normalizing each of these would've meant schema changes every two weeks. Instead, we stored preferences as JSONB with strategic GIN indexes.

The Real Question: When, Not If

JSONB isn't a replacement for normalization—it's a tool for data that's genuinely flexible. Ask yourself:

Is the structure likely to change? Use JSONB.
Do you need to filter or aggregate on every field? Normalize it.
Is this metadata or configuration? JSONB.
Is this your primary data model? Normalize.

In CitizenApp, user organization_settings is JSONB because orgs customize features individually. But users themselves? That's relational. The email field never changes structure, so it doesn't belong in JSON.

Practical Schema Design

Here's how I structure tables with JSONB columns:

CREATE TABLE organizations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    settings JSONB DEFAULT '{}',
    metadata JSONB DEFAULT '{}'
);

-- Critical: Add GIN indexes for queryability
CREATE INDEX idx_org_settings_gin ON organizations USING GIN (settings);
CREATE INDEX idx_org_settings_plan ON organizations USING GIN (settings) 
    WHERE settings->>'plan' IS NOT NULL;

The second index is intentional—I prefer targeted indexes on paths you'll actually query. Full GIN indexes on huge JSONB columns burn memory without helping specific queries.

Querying JSONB: The Operators You Need

PostgreSQL gives you powerful operators. Learn them:

-- Arrow operators: -> (returns JSONB), ->> (returns TEXT)
SELECT * FROM organizations 
WHERE settings->>'plan' = 'enterprise';

-- Deep path access
SELECT * FROM organizations 
WHERE (settings->'features'->>'ai_enabled')::boolean = true;

-- Existence checking
SELECT * FROM organizations 
WHERE settings ? 'legacy_mode';

-- Array containment
SELECT * FROM organizations 
WHERE settings->'allowed_domains' @> '["example.com"]'::jsonb;

-- JSONB contains (subset check)
SELECT * FROM organizations 
WHERE settings @> '{"plan": "enterprise"}'::jsonb;

That last one is powerful. @> checks if the left JSONB contains all key-value pairs from the right. Combined with a GIN index, it's incredibly fast.

FastAPI Integration: Type Safety Matters

Here's how I handle JSONB in FastAPI with SQLAlchemy. Type safety prevents silent bugs:

from pydantic import BaseModel, Field
from sqlalchemy import Column, UUID, JSONB, String
from sqlalchemy.orm import declarative_base
from typing import Optional, Dict, Any
import uuid

Base = declarative_base()

class OrganizationSettingsSchema(BaseModel):
    plan: str = Field(default="free", pattern="^(free|pro|enterprise)$")
    ai_features_enabled: bool = True
    max_users: int = 10
    custom_branding: Optional[Dict[str, str]] = None

    model_config = {"extra": "allow"}  # Allow other fields

class Organization(Base):
    __tablename__ = "organizations"

    id = Column(UUID, primary_key=True, default=uuid.uuid4)
    name = Column(String, nullable=False)
    settings = Column(JSONB, default={}, nullable=False)

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

app = FastAPI()

@app.post("/organizations/{org_id}/settings")
async def update_settings(
    org_id: str,
    settings: OrganizationSettingsSchema,
    db: Session
):
    org = db.query(Organization).filter(Organization.id == org_id).first()
    if not org:
        raise HTTPException(status_code=404)

    # Validate before storing
    org.settings = settings.model_dump(exclude_none=True)
    db.commit()
    return org.settings

@app.get("/organizations")
async def list_by_plan(plan: str, db: Session):
    # Query JSONB directly—PostgreSQL does the filtering
    return db.query(Organization).filter(
        Organization.settings.astext.op('->>')('plan') == plan
    ).all()

Notice: I use Pydantic schemas to validate before storing JSONB. This prevents garbage data that looks valid in the database but breaks your application logic. This burned me when developers pushed random nested objects into settings without validation.

Schema Evolution Without Migrations

This is where JSONB shines. Adding a new setting field requires zero migrations:

# Old code
settings = {"plan": "pro", "ai_enabled": true}

# New code adds a field—no schema changes needed
settings = {"plan": "pro", "ai_enabled": true, "webhook_url": "https://..."}

# Backfill safely with a migration script, not a schema migration
db.query(Organization).filter(
    Organization.settings['webhook_url'].astext == None
).update({"settings": func.jsonb_set(
    Organization.settings, 
    '{webhook_url}', 
    '"https://default.webhook"'
)})

That jsonb_set function is your friend for bulk updates without downtime.

Gotcha: N+1 Queries on Related Data

This burned me hard. JSONB looks like it solves everything, so I stored nested relationships as JSON arrays:

# Bad: Storing user IDs in JSONB
settings = {"allowed_user_ids": [1, 2, 3, 4, 5]}

# Then querying:
SELECT * FROM organizations WHERE settings->'allowed_user_ids' @> '[2]'::jsonb

This works, but it's inefficient at scale and loses referential integrity. If you need to query on that data frequently, normalize it to a junction table. JSONB is for metadata, not foreign keys.

Indexing Strategy

I learned this the hard way:

-- Over-indexing (wastes space)
CREATE INDEX ON organizations USING GIN (settings);
CREATE INDEX ON organizations USING GIN (settings) WHERE settings ? 'plan';

-- Smart indexing (use targeted indexes)
CREATE INDEX idx_org_plan ON organizations ((settings->>'plan'));
CREATE INDEX idx_org_ai_features ON organizations USING GIN (settings) 
    WHERE (settings->>'ai_enabled')::boolean = true;

Targeted B-tree indexes on scalar values are faster than GIN when you're filtering on a single field. GIN wins when you need @> or ? operators.

The Verdict

JSONB isn't a shortcut to schema design—it's a tool for controlled flexibility. Use it for settings, preferences, metadata, and evolving features. Keep your core data relational. Index strategically. Validate aggressively in your application layer.

Done right, you get rapid iteration without the chaos of schemaless databases. Done wrong, you end up with a blob column that's impossible to query. The difference is discipline.

Design Systems in React: Building Themeable, Typed Component Libraries with TypeScript

Ugur Aslim — Sat, 25 Jul 2026 09:57:11 +0000

I've built three production design systems, and I can tell you the difference between "a folder of React components" and an actual scalable design system comes down to one thing: typing your design tokens and enforcing consistency at compile time, not runtime.

Most teams start with a component library and hope theming magics itself into existence. That's how you end up with six different shades of blue and components that break when someone changes CSS variables. I prefer building the constraint layer first—define your design tokens as TypeScript types, generate CSS from them, and make it impossible to ship inconsistent UI.

The Problem With Traditional Approaches

When I started CitizenApp, I inherited a Tailwind-only approach. Seemed fine until we needed dark mode, custom branding per tenant, and WCAG AAA compliance across all themes. Suddenly I'm managing CSS variable overrides in 15 places, components are picking arbitrary colors, and nothing validates.

Here's what burned me: CSS-in-JS without types is just inline styles with extra steps. You get no autocomplete, no exhaustiveness checking, no way to enforce "use only these colors." And if you use Tailwind classes everywhere, good luck swapping themes or detecting when someone used a color that doesn't exist in your design system.

I switched to a hybrid: TypeScript-first design tokens with CSS variable generation, paired with Tailwind for utilities. This gives me strict theming, type safety, and the developer experience I actually want.

Building a Type-Safe Design System

Let's start with the foundation—design tokens as TypeScript enums and objects:

// src/tokens/colors.ts
export const colorTokens = {
  // Semantic colors (what I actually use in components)
  primary: {
    50: '#f0f9ff',
    100: '#e0f2fe',
    500: '#0ea5e9',
    600: '#0284c7',
    900: '#0c2d6b',
  },
  secondary: {
    50: '#faf5ff',
    500: '#a855f7',
    900: '#5b21b6',
  },
  neutral: {
    0: '#ffffff',
    50: '#f9fafb',
    100: '#f3f4f6',
    500: '#6b7280',
    900: '#111827',
  },
  // Status colors (always the same meaning)
  success: '#10b981',
  warning: '#f59e0b',
  error: '#ef4444',
  info: '#3b82f6',
} as const;

export type ColorToken = keyof typeof colorTokens;
export type ColorScale = keyof typeof colorTokens[ColorToken];

Now create a theme configuration that's actually typed:

// src/tokens/theme.ts
import { colorTokens } from './colors';

export const themes = {
  light: {
    colors: {
      background: colorTokens.neutral[0],
      foreground: colorTokens.neutral[900],
      border: colorTokens.neutral[200],
      primary: colorTokens.primary[600],
      primaryHover: colorTokens.primary[700],
      success: colorTokens.success,
      error: colorTokens.error,
    },
  },
  dark: {
    colors: {
      background: colorTokens.neutral[900],
      foreground: colorTokens.neutral[50],
      border: colorTokens.neutral[700],
      primary: colorTokens.primary[500],
      primaryHover: colorTokens.primary[400],
      success: colorTokens.success,
      error: colorTokens.error,
    },
  },
} as const;

export type ThemeName = keyof typeof themes;
export type ThemeConfig = (typeof themes)[ThemeName];
export type SemanticColor = keyof ThemeConfig['colors'];

// Generate CSS variables programmatically
export function generateThemeCss(themeName: ThemeName): string {
  const theme = themes[themeName];
  const cssVars = Object.entries(theme.colors)
    .map(([key, value]) => `--color-${key}: ${value};`)
    .join('\n  ');
  return `[data-theme="${themeName}"] {\n  ${cssVars}\n}`;
}

Generate actual CSS at build time (or runtime in dev):

// src/tokens/generate.ts
import { themes } from './theme';
import fs from 'fs';

export function generateCssFile() {
  const allThemes = Object.keys(themes)
    .map((themeName) => generateThemeCss(themeName as ThemeName))
    .join('\n\n');

  const css = `/* Auto-generated theme CSS. Do not edit manually. */\n${allThemes}`;
  fs.writeFileSync('src/styles/themes.css', css);
  console.log('✓ Generated theme CSS');
}

if (require.main === module) {
  generateCssFile();
}

Type-Safe Components Using Tokens

Now your components are type-constrained. This is where the magic happens:

// src/components/Button.tsx
import { SemanticColor, themes } from '../tokens/theme';
import { ReactNode } from 'react';

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  color?: SemanticColor;
  size?: 'sm' | 'md' | 'lg';
  children: ReactNode;
  className?: string;
}

export const Button = ({
  variant = 'primary',
  color = 'primary',
  size = 'md',
  children,
  className = '',
}: ButtonProps) => {
  const sizeClasses = {
    sm: 'px-2 py-1 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg',
  };

  // This TypeScript ensures `color` is always a valid semantic color
  const baseStyle = `
    bg-[var(--color-${color})]
    hover:bg-[var(--color-${color}Hover)]
    text-[var(--color-foreground)]
    border border-[var(--color-border)]
    rounded-md
    transition-colors
    ${sizeClasses[size]}
    ${className}
  `;

  return (
    <button
      className={baseStyle}
      data-variant={variant}
    >
      {children}
    </button>
  );
};

The killer feature: if you typo a color name or try to use a non-existent semantic color, TypeScript catches it immediately. No runtime surprise, no shipped bug.

Multi-Tenant Theming in Practice

Here's how I handle per-tenant branding in CitizenApp:

// src/hooks/useTheme.ts
import { useContext, useMemo } from 'react';
import { ThemeContext } from '../context/ThemeContext';
import { themes, type ThemeName } from '../tokens/theme';

export function useTheme(themeName?: ThemeName) {
  const contextTheme = useContext(ThemeContext);
  const resolvedTheme = themeName || contextTheme?.theme || 'light';

  // Memoize to prevent re-renders when theme doesn't change
  return useMemo(() => themes[resolvedTheme], [resolvedTheme]);
}

At the app level:

// src/App.tsx
import { ThemeProvider } from './context/ThemeContext';
import { useThemeFromUser } from './hooks/useThemeFromUser';

export default function App() {
  const userTheme = useThemeFromUser(); // 'light' | 'dark' from JWT

  return (
    <ThemeProvider theme={userTheme}>
      <div data-theme={userTheme}>
        <YourApp />
      </div>
    </ThemeProvider>
  );
}

Gotcha: CSS Variable Specificity and Dark Mode

When I first deployed this, I discovered Tailwind's opacity modifiers don't work with CSS variables the way you'd expect. bg-[var(--color-primary)]/50 doesn't let you control opacity on a custom property—you need to either use RGBA values or double-define with fallbacks.

I worked around this by extending Tailwind config to define color utilities that respect my tokens:

// tailwind.config.js
export default {
  theme: {
    colors: {
      primary: 'var(--color-primary)',
      secondary: 'var(--color-secondary)',
      // ... all semantic colors
    },
  },
};

Now bg-primary works perfectly and respects your theme's CSS variables at runtime.

Why This Matters

You avoid the graveyard of "design system" projects that nobody uses because they're:

Too rigid (can't adapt to real product needs)
Too loose (developers make decisions, inconsistency spreads)
Poorly typed (nobody discovers features because there's no autocomplete)

A TypeScript-first design system with generated CSS is the sweet spot: constraints at compile time, flexibility at runtime, and developer experience that makes people actually use it.

This approach scales. I've used this pattern across five projects now, and it's the only theming strategy where adding a new color or changing a theme doesn't require touching component code.

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

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

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

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

Why Your Current Tests Probably Suck

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

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

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

Setting Up pytest with FastAPI and PostgreSQL

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

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

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


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

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

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


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


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

    yield session

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


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

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

    yield TestClient(app)

    app.dependency_overrides.clear()

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

Writing Tests That Actually Matter

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

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

router = APIRouter()


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

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

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

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

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

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


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


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


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


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

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


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

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

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

Parametrized Tests for Edge Cases

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

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

Gotcha: Transaction Isolation and Async

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

My workaround:

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

    scoped = scoped_session(TestingSessionLocal)

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

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

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

Running Tests in CI

Use GitHub Actions with a Postgres container:


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

on: [push, pull_request]

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

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

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

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

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

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

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

The Problem with Generic Monorepo Caching

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

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

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

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

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

Smart Caching: Cache per Workspace

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

name: CI

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

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

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

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

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

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

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

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

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

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

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

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

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

Let me break down what's happening:

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

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

Why This Matters: Real Numbers

For CitizenApp, we have four main workspaces:

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

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

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

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

Gotcha: Shared Dependencies and Hoisted Packages

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

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

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

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

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

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

This is hacky, though. I avoid it.

One More Thing: Matrix Optimization

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

Summary

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

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

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

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

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

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

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

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

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

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

The Solution: Defensive Middleware Layers

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

Here's the core structure:

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

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

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

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

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

        response = await call_next(request)
        return response

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

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

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

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

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

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

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

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

This does three things I care about:

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

Rate Limiting and Quota Enforcement: The Next Layer

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

from redis import Redis
import json

redis_client = Redis(decode_responses=True)

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

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

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

        if not tenant_id:
            return await call_next(request)

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

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

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

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

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

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

What I Missed (and learned from)

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

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

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

from contextvars import ContextVar

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

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

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

The Real Win

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

That's what defensive middleware buys you in production.

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

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

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

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

Why useTransition Matters for AI-Heavy Apps

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

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

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

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

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

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

With useTransition, React knows to keep the UI responsive:

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

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

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

The Real-World CitizenApp Example

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

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

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

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

  const [isPending, startTransition] = useTransition();

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

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

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

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

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

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

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

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

Backend Considerations: FastAPI + SQLAlchemy

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

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

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

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

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

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

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

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

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

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

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

Gotcha: useTransition with Async State Updates

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

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

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

What I Missed Initially

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

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

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

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

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

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

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

Why Replicas Solve the Wrong Problem (But Still Work)

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

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

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

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

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

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

Setting Up Render Replicas (The Easy Part)

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

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

SQLAlchemy Read-Write Routing (The Implementation)

Here's the pattern I use in production:

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

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

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

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

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

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

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

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

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

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

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

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

Usage in FastAPI endpoints:

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

app = FastAPI()

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

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

        return {"events_by_date": result}

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

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

        return event

Replica Lag: The Silent Killer

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

Monitor it obsessively:

from datetime import datetime
from sqlalchemy import text

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

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

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

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

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

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

Failover: When Your Replica Becomes Your Primary

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

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

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

Gotcha: Replica Drift and Foreign Keys

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

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

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

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

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

The Real Win

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

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

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

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

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

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

Why Standard Astro Islands Fail for SaaS Marketing

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

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

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

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

The Architecture: Deferred Islands in Practice

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

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

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

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

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

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

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

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

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

Now the Astro template:

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

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

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

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

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

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

Aggressive Code Splitting with Astro's Integration Config

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

I prefer explicit code splitting:

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

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

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

Measuring the Impact

For CitizenApp's landing page:

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

Gotcha: Form State and URL Sync

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

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

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

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

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

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

  // ... rest of component
}

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

Why This Matters for SaaS

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

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

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

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

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

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

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

Why Connection Pooling Matters on the Server

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

I prefer explicit connection pooling with a bounded queue:

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

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

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

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

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

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

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

pool = ConnectionPool(max_connections=5000)

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

The Heartbeat Pattern Prevents Zombie Connections

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

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

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

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

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

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

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

        this.onMessage(message);
      };

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

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

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

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

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

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

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

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

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

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

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

And on the server:

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

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

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

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

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

Graceful Reconnection with Exponential Backoff

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

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

Message Queue During Disconnection

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

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

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

Gotcha: Message Ordering During Reconnection

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

I solved this with idempotent message IDs:

private messageId = 0;

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

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

On the server, deduplicate:

seen_ids = set()

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

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

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