Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/hono

references/full-stack-web-architecture-consolidated.md

View on GitHub
# Modern Full-Stack Web Application Architecture
## A Comprehensive Guide to Building Type-Safe, Real-Time Applications

---

## Table of Contents

1. [Executive Overview](#executive-overview)
2. [Authentication & Authorization](#authentication--authorization)
3. [Frontend Architecture](#frontend-architecture)
4. [Backend & State Management](#backend--state-management)
5. [API Integration Patterns](#api-integration-patterns)
6. [Type Safety & Schema Validation](#type-safety--schema-validation)
7. [Real-Time Features](#real-time-features)
8. [Deployment](#deployment)
9. [Observability](#observability)
10. [Best Practices & Patterns](#best-practices--patterns)

---

## Executive Overview

### Full-Stack Architecture Philosophy

This document presents a comprehensive architecture for building modern, type-safe, real-time web applications. The approach centers on a strategic separation of concerns that prioritizes scalability, low latency, and maintainability while leveraging the best of contemporary web technologies.

#### Core Architectural Pillars

**1. TanStack Start** – Full-stack frontend framework providing:
- File-based, type-safe routing
- Server-Side Rendering (SSR)
- Server-to-client streaming
- Unified server and client function execution

**2. Convex** – Real-time state management and persistence:
- Single source of truth for application data
- WebSocket-based real-time synchronization across all clients
- Chat history, live metrics, and user presence management

**3. BetterAuth** – Self-hosted authentication provider:
- OpenID Connect (OIDC) support
- JWT-based authentication
- Multi-tenancy through organization-based access control

**4. Cloudflare/Netlify** – Edge and serverless deployment:
- Global CDN distribution
- Edge function execution
- Zero-config deployment workflows

**5. Type Safety** – End-to-end type consistency:
- Unified schema definitions (BAML → Pydantic + Zod)
- Compile-time validation throughout the stack
- Runtime validation at data boundaries

---

## Authentication & Authorization

### BetterAuth Setup and Configuration

BetterAuth serves as the central Identity Provider (IdP) using OpenID Connect. All components (frontend and backend) rely on BetterAuth for user authentication, with Supabase PostgreSQL as the primary database backing.

#### Architecture Overview

```
User → TanStack Frontend → BetterAuth (via Hono) → PostgreSQL
                         ↓
                    JWT/Session
                         ↓
           Convex Backend ← validates JWT
           Hono API ← validates JWT
```

#### Core Components

**BetterAuth (OIDC Provider)**
- Handles user authentication (email/password, social logins)
- Issues OIDC tokens (ID/Access tokens) via standard flows (Authorization Code with PKCE)
- Persists user profiles, credentials, sessions, and OIDC client data in PostgreSQL

**Supabase PostgreSQL**
- Stores BetterAuth's data tables (users, sessions, accounts)
- Can also store application data
- Single database instance for simplicity (can be separated in production)

**Hono (Backend API)**
- Lightweight TypeScript web server
- Integrates BetterAuth library as middleware/route handlers
- Hosts BetterAuth authentication endpoints (`/api/auth/*` routes)
- Provides protected application APIs

#### Docker Compose Configuration

```yaml
services:
  db:
    image: postgres:15-alpine
    container_name: supabase-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: postgres
    volumes:
      - supabase-data:/var/lib/postgresql/data
    networks:
      - internal

  api:
    build: ./hono-api
    container_name: hono-api
    depends_on:
      - db
      - convex
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/postgres
      BETTER_AUTH_SECRET: ${AUTH_SECRET}
      BETTER_AUTH_URL: http://localhost:4000
    networks:
      - internal
    ports:
      - "4000:4000"

  convex:
    image: ghcr.io/get-convex/convex-backend:latest
    container_name: convex-backend
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://postgres:${DB_PASSWORD}@db
      CONVEX_CLOUD_ORIGIN: http://convex:3210
      CONVEX_SITE_ORIGIN: http://convex:3211
    networks:
      - internal
    ports:
      - "3210:3210"
      - "3211:3211"

  frontend:
    build: ./tanstack-start
    container_name: tanstack-frontend
    depends_on:
      - api
    environment:
      PUBLIC_AUTH_URL: "http://localhost:4000/api/auth"
      PUBLIC_API_URL: "http://localhost:4000/api"
      PUBLIC_CONVEX_URL: "http://localhost:3210"
    networks:
      - internal
    ports:
      - "3000:3000"

networks:
  internal:
    driver: bridge

volumes:
  supabase-data:
```

#### Environment Variables & Secrets

**Critical Configuration:**

1. **Database Password** – Strong password for PostgreSQL
2. **BetterAuth Secret** – Long random string for encryption/hashing
   ```bash
   openssl rand -hex 32
   ```
3. **BetterAuth URL** – Base URL of the application (localhost in dev, production domain in prod)
4. **OIDC Client Config** – Client ID and redirect URIs
5. **Trusted Origins (CORS)** – Allowed origins for requests
   ```typescript
   trustedOrigins: ['http://localhost:3000']
   ```

### Convex OIDC Integration

Convex is configured to trust BetterAuth as an OIDC provider through `auth.config.ts`:

```typescript
// convex/auth.config.ts
export default {
  providers: [
    {
      domain: "http://localhost:4000", // BetterAuth issuer URL
      applicationID: "tanstack_frontend" // OIDC Client ID
    }
  ]
};
```

This configuration ensures:
- Convex accepts tokens where `iss` matches the BetterAuth URL
- Convex verifies tokens using BetterAuth's JWKS endpoint
- User identity is available in Convex functions via `auth.getUser()`

### JWT Validation Flow

**1. User Login (Frontend → BetterAuth)**
- User initiates login through TanStack Start app
- Frontend redirects to BetterAuth's OIDC authorization endpoint
- User provides credentials on BetterAuth's interface

**2. Authentication & Token Issuance**
- BetterAuth verifies credentials against PostgreSQL
- Creates user session persisted in database
- Issues ID token (JWT) and access token
- Tokens signed by BetterAuth with claims:
  - `sub`: User ID
  - `iss`: BetterAuth URL
  - `aud`: Application client ID
  - `exp`: Expiration timestamp

**3. Frontend Stores Token**
- Tokens stored in memory or HttpOnly cookie
- Access token included as `Authorization: Bearer <token>` header
- Convex client configured with ID token via `setAuth(token)`

**4. Backend Verification (Hono)**
```typescript
import { Hono } from 'hono';
import { auth } from './auth';

const app = new Hono();

app.use('/api/*', async (c, next) => {
  // BetterAuth middleware validates JWT
  const session = await auth.getSession(c);
  if (!session) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
  c.set('user', session.user);
  await next();
});

app.get('/api/profile', async (c) => {
  const user = c.get('user');
  // User is authenticated and available
  return c.json({ user });
});
```

**5. Backend Verification (Convex)**
- Convex validates JWT signature using BetterAuth's JWKS
- Checks `iss`, `aud`, and `exp` claims
- Makes user identity available in server functions:

```typescript
// convex/users.ts
import { query } from "./_generated/server";

export const getCurrentUser = query({
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      throw new Error("Not authenticated");
    }
    return identity;
  }
});
```

### Multi-Tenancy Patterns

**Organization-Based Access Control:**

1. **JWT Claims**
   - Include `orgId` in JWT issued by BetterAuth
   - Custom claims added during token creation

2. **Query Filtering**
   - All queries scoped to user's organization
   - Apply filters at database level

```typescript
// Hono API
app.get('/api/contracts', async (c) => {
  const user = c.get('user');
  const contracts = await db.query(
    'SELECT * FROM contracts WHERE org_id = $1',
    [user.orgId]
  );
  return c.json(contracts);
});

// Convex Query
export const listContracts = query({
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    return await ctx.db
      .query("contracts")
      .filter(q => q.eq(q.field("orgId"), identity.orgId))
      .collect();
  }
});
```

3. **GraphQL Auth Rules**
   - Neo4j GraphQL library supports `@authorization` directives
   - Inject tenant context at schema level

```graphql
type Contract @authorization(filter: [{ where: { orgId: "$jwt.orgId" } }]) {
  id: ID!
  title: String!
  orgId: String!
  parties: [Party!]!
}
```

---

## Frontend Architecture

### TanStack Start Routing

TanStack Start provides a full-stack foundation with file-based routing, SSR, and server-to-client streaming.

#### File-Based Routing Structure

```
src/routes/
├── dashboard/
│   ├── route.tsx          # Main layout with <Outlet />
│   ├── index.tsx          # Dashboard home (/dashboard)
│   ├── contracts/
│   │   ├── index.tsx      # Contract list (/dashboard/contracts)
│   │   └── $id.tsx        # Contract detail (/dashboard/contracts/:id)
│   └── chat-fullscreen.tsx # Full-page chat (/dashboard/chat-fullscreen)
└── index.tsx              # Root route (/)
```

#### Layout Components

**Main Dashboard Layout (`src/routes/dashboard/route.tsx`):**

```typescript
import { createFileRoute, Outlet } from '@tanstack/react-router';
import { DashboardHeader } from '~/components/DashboardHeader';
import { getInitialDashboardStats } from '~/server/stats';

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    // Pre-fetch data during SSR
    const stats = await getInitialDashboardStats();
    return { stats };
  },
  component: DashboardLayout
});

function DashboardLayout() {
  const { stats } = Route.useLoaderData();

  return (
    <div className="dashboard-container">
      <DashboardHeader />
      <div className="dashboard-content">
        <div className="chat-panel">
          {/* Chat interface */}
        </div>
        <div className="stats-panel">
          {/* Live metrics */}
        </div>
        <div className="main-content">
          <Outlet /> {/* Renders child routes */}
        </div>
      </div>
    </div>
  );
}
```

#### SSR and Route Loaders

Route loaders enable pre-fetching data before page render, eliminating loading spinners and content layout shifts.

**Server Function for Data Fetching:**

```typescript
// src/server/stats.ts
import { createServerFn } from '@tanstack/start';
import { useConvexAuth } from 'convex/react';

export const getInitialDashboardStats = createServerFn({ method: 'GET' })
  .handler(async ({ context }) => {
    // Secure server-side data fetching
    const convex = context.convex;
    const stats = await convex.query(api.stats.getDashboardData);
    return stats;
  });
```

**Route with Loader:**

```typescript
export const Route = createFileRoute('/dashboard')({
  loader: () => getInitialDashboardStats(),
  component: DashboardLayout
});
```

During initial page load:
1. TanStack's SSR engine executes the loader
2. Calls the server function and waits for data
3. Streams HTML to client with data already populated
4. Client-side React hydrates the application

### SSR and Streaming Capabilities

TanStack Start supports streaming responses for optimal performance:

**Streaming Server Function:**

```typescript
// src/server/ai.ts
export const askRepoAI = createServerFn({ method: 'POST' })
  .handler(async function* ({ data }) {
    // Async generator for streaming
    const { prompt } = data;

    // Call CodeRabbit API
    const response = await fetch('https://api.coderabbit.ai/chat', {
      method: 'POST',
      body: JSON.stringify({ prompt }),
      headers: { 'Content-Type': 'application/json' }
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      yield chunk; // Stream to client
    }
  });
```

**Client-Side Consumption:**

```typescript
import { useState } from 'react';
import { askRepoAI } from '~/server/ai';

function ChatComponent() {
  const [message, setMessage] = useState('');
  const [response, setResponse] = useState('');

  const handleSubmit = async () => {
    const stream = await askRepoAI({ data: { prompt: message } });
    const reader = stream.body.getReader();
    const decoder = new TextDecoder();

    let fullResponse = '';
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      fullResponse += chunk;
      setResponse(fullResponse); // Update UI incrementally
    }

    // Persist to Convex after completion
    await convex.mutation(api.messages.save, {
      prompt: message,
      response: fullResponse
    });
  };

  return (
    <div>
      <input value={message} onChange={e => setMessage(e.target.value)} />
      <button onClick={handleSubmit}>Send</button>
      <div>{response}</div>
    </div>
  );
}
```

---

## Backend & State Management

### Convex as Unified Real-Time Backend

Convex provides a reactive backend with automatic WebSocket synchronization, making it the single source of truth for all persistent, shared state.

#### Core Concepts

**1. Queries** – Read data reactively:
```typescript
// convex/messages.ts
import { query } from "./_generated/server";

export const getAll = query({
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    return await ctx.db
      .query("messages")
      .filter(q => q.eq(q.field("userId"), identity.subject))
      .order("desc")
      .collect();
  }
});
```

**2. Mutations** – Write data:
```typescript
// convex/messages.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const save = mutation({
  args: {
    prompt: v.string(),
    response: v.string()
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    await ctx.db.insert("messages", {
      userId: identity.subject,
      prompt: args.prompt,
      response: args.response,
      timestamp: Date.now()
    });
  }
});
```

**3. Actions** – External API calls:
```typescript
// convex/external.ts
import { action } from "./_generated/server";

export const callExternalAPI = action({
  handler: async (ctx, args) => {
    // Actions can make external HTTP requests
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();

    // Can call mutations to persist results
    await ctx.runMutation(api.data.store, { data });
    return data;
  }
});
```

#### Real-Time Sync via WebSockets

**Client Setup:**

```typescript
// src/lib/convex.tsx
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

export function ConvexClientProvider({ children }) {
  return (
    <ConvexProvider client={convex}>
      {children}
    </ConvexProvider>
  );
}
```

**Using Queries in Components:**

```typescript
import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

function ChatHistory() {
  // Automatically subscribes to updates via WebSocket
  const messages = useQuery(api.messages.getAll);
  const saveMessage = useMutation(api.messages.save);

  // When ANY client calls saveMessage, this component re-renders
  // across ALL connected clients automatically

  return (
    <div>
      {messages?.map(msg => (
        <div key={msg._id}>
          <p><strong>Prompt:</strong> {msg.prompt}</p>
          <p><strong>Response:</strong> {msg.response}</p>
        </div>
      ))}
    </div>
  );
}
```

#### Hybrid Streaming Model

The architecture employs two complementary real-time mechanisms:

**1. Ephemeral Token Streaming (TanStack Start)**
- Used exclusively for AI agent's in-progress response
- Server function returns ReadableStream via async generator
- Provides lowest-latency "typing" effect
- Unidirectional, ephemeral, server-to-client push
- Only active user sees the stream

**2. Persistent State Sync (Convex)**
- Used for all committed application state
- Bi-directional WebSocket-based synchronization
- Accessed via `useQuery` hook
- All clients see updates instantly
- Provides durable, shared source of truth

**Implementation Pattern:**

```typescript
async function handleChatSubmit(prompt: string) {
  // 1. Optimistic UI update
  setMessages(prev => [...prev, { prompt, response: '', pending: true }]);

  // 2. Stream response from AI
  const stream = await askRepoAI({ data: { prompt } });
  let fullResponse = '';

  for await (const chunk of stream) {
    fullResponse += chunk;
    setCurrentResponse(fullResponse); // Update local state only
  }

  // 3. Commit to Convex (all clients will receive via WebSocket)
  await convex.mutation(api.messages.save, {
    prompt,
    response: fullResponse
  });

  // 4. Clear local state (Convex query will now provide the data)
  setCurrentResponse('');
}
```

This "stream-then-commit" model provides:
- Immediate feedback for the active user (streaming)
- Persistent, synchronized state across all clients (Convex)
- Best UX without sacrificing consistency

---

## API Integration Patterns

### OpenAPI/TypeScript Client Generation

For external APIs or microservices, generate type-safe TypeScript clients from OpenAPI specifications.

#### Choosing a Code Generator

**swagger-typescript-api** (Recommended for Node/Bun)
- No Java dependency (pure Node.js)
- Supports Fetch API and Axios
- Generates single file or modular structure
- Active maintenance and good TypeScript support

**Example Generation:**

```bash
# Install
npm install --save-dev swagger-typescript-api

# Generate client
npx swagger-typescript-api generate \
  --path ./openapi/api-spec.json \
  --output src/apiClient/ \
  --name ApiClient.ts \
  --api-class-name ApiClient \
  --axios
```

**Generated Usage:**

```typescript
// src/lib/apiClient.ts
import { ApiClient } from './apiClient/ApiClient';

const client = new ApiClient({
  baseURL: "https://api.example.com/v1",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`
  }
});

// Fully typed methods
const contracts = await client.contracts.listContracts({
  orgId: "123"
});
```

#### Alternative: openapi-typescript-codegen

```bash
npx openapi-typescript-codegen \
  --input api-spec.json \
  --output src/apiClient \
  --client fetch
```

Supports multiple HTTP client options (fetch, node-fetch, Axios, XHR).

### GraphQL vs tRPC vs REST Decision Matrix

| Criterion | GraphQL | tRPC | REST |
|-----------|---------|------|------|
| **Type Safety** | Schema-based, needs codegen | End-to-end TypeScript inference | Manual or codegen required |
| **Learning Curve** | Moderate (new query language) | Low (TypeScript functions) | Low (standard HTTP) |
| **Over-fetching** | Solved (client specifies fields) | N/A (function calls) | Common issue |
| **Real-time** | Subscriptions available | Not built-in | SSE/WebSockets needed |
| **Tooling** | Excellent (Apollo, Relay) | Growing (tRPC client) | Standard HTTP tools |
| **Best For** | Complex data graphs, mobile apps | Full-stack TypeScript monorepos | Public APIs, simple services |

**Recommendation for Modern Stack:**

- **Use tRPC** for internal frontend ↔ backend communication in TypeScript monorepos
- **Use GraphQL** if exposing API to external clients or need complex nested queries
- **Use REST** for simple services or when interoperating with non-TypeScript systems

### Server Functions as API Gateway

TanStack Start server functions act as a secure gateway between frontend and backend services.

**Pattern: Server Function → Multiple Backends:**

```typescript
// src/server/data.ts
import { createServerFn } from '@tanstack/start';
import { ApiClient } from '~/lib/apiClient';
import { convex } from '~/lib/convex';

export const getDashboardData = createServerFn({ method: 'GET' })
  .handler(async ({ context }) => {
    const user = context.user; // From auth middleware

    // Parallel data fetching from multiple sources
    const [contracts, metrics, aiSummary] = await Promise.all([
      // External API via generated client
      ApiClient.contracts.list({ orgId: user.orgId }),

      // Convex query
      convex.query(api.metrics.getLatest, { userId: user.id }),

      // AI service
      fetch('https://ai-service.com/summarize', {
        method: 'POST',
        body: JSON.stringify({ orgId: user.orgId })
      }).then(r => r.json())
    ]);

    return { contracts, metrics, aiSummary };
  });
```

**Benefits:**
- Centralized authentication/authorization
- API key security (never exposed to client)
- Cross-origin request handling
- Response transformation and caching
- Error handling and retry logic

---

## Type Safety & Schema Validation

### BAML for Structured LLM Outputs

BAML (Boundary AI Markup Language) provides a single source of truth for domain models, generating corresponding Pydantic (Python) and TypeScript/Zod (JavaScript) types.

#### Defining Domain Classes in BAML

```baml
// baml_src/domain.baml

class DocumentChunk {
  id string                 @description("Unique chunk identifier")
  repo string               @description("Repository name or ID")
  file_path string?         @description("Source file path (if applicable)")
  content string            @description("Text content of the chunk")
  embedding float[]         @description("Embedding vector of the content")
}

class ToolCall {
  tool_name string          @description("Name of the tool to invoke")
  params map<string, any>   @description("Input parameters for the tool")
  result any?               @description("Result returned by the tool")
}

class RepoSummary {
  repo_name string          @description("Repository name")
  description string        @description("High-level description")
  main_topics string[]      @description("Key topics or technologies")
  file_count int            @description("Number of files analyzed")
}

class UserQuery {
  user_id string            @description("ID of the user making the query")
  query_text string         @description("The user's question or prompt")
  timestamp datetime        @description("When the query was made")
}
```

#### Generated Pydantic Models

```python
# Auto-generated by BAML (baml_client/types.py)
from pydantic import BaseModel, Field
from typing import List, Optional, Any, Dict
from datetime import datetime

class DocumentChunk(BaseModel):
    id: str
    repo: str
    file_path: Optional[str] = None
    content: str
    embedding: List[float]

class ToolCall(BaseModel):
    tool_name: str
    params: Dict[str, Any]
    result: Optional[Any] = None

class RepoSummary(BaseModel):
    repo_name: str
    description: str
    main_topics: List[str]
    file_count: int

class UserQuery(BaseModel):
    user_id: str
    query_text: str
    timestamp: datetime
```

#### Generated TypeScript Types

```typescript
// Auto-generated by BAML (baml_client/types.ts)
export interface DocumentChunk {
  id: string;
  repo: string;
  file_path?: string;
  content: string;
  embedding: number[];
}

export interface ToolCall {
  tool_name: string;
  params: Record<string, any>;
  result?: any;
}

export interface RepoSummary {
  repo_name: string;
  description: string;
  main_topics: string[];
  file_count: number;
}

export interface UserQuery {
  user_id: string;
  query_text: string;
  timestamp: string; // ISO 8601 string
}
```

### Zod for Runtime Validation

Create Zod schemas for runtime validation at data boundaries:

```typescript
// src/lib/schemas.ts
import { z } from 'zod';

export const DocumentChunkSchema = z.object({
  id: z.string(),
  repo: z.string(),
  file_path: z.string().optional(),
  content: z.string(),
  embedding: z.array(z.number())
});

export const ToolCallSchema = z.object({
  tool_name: z.string(),
  params: z.record(z.any()),
  result: z.any().optional()
});

export const RepoSummarySchema = z.object({
  repo_name: z.string(),
  description: z.string(),
  main_topics: z.array(z.string()),
  file_count: z.number().int()
});

export const UserQuerySchema = z.object({
  user_id: z.string(),
  query_text: z.string(),
  timestamp: z.string().datetime()
});

// Infer types from schemas
export type DocumentChunk = z.infer<typeof DocumentChunkSchema>;
export type ToolCall = z.infer<typeof ToolCallSchema>;
export type RepoSummary = z.infer<typeof RepoSummarySchema>;
export type UserQuery = z.infer<typeof UserQuerySchema>;
```

### End-to-End Type Safety

**Server-Side Validation (Hono):**

```typescript
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { UserQuerySchema, DocumentChunkSchema } from '~/lib/schemas';

const app = new Hono();

app.post(
  '/ask',
  zValidator('json', UserQuerySchema),
  async (c) => {
    const query = c.req.valid('json'); // Typed as UserQuery

    // Process query...
    const results = await searchMemory(query);

    // Validate response
    const validated = DocumentChunkSchema.array().parse(results);
    return c.json(validated);
  }
);
```

**Client-Side Validation (TanStack Router):**

```typescript
import { createFileRoute } from '@tanstack/react-router';
import { DocumentChunkSchema } from '~/lib/schemas';

export const Route = createFileRoute('/search')({
  loader: async ({ search: { q } }) => {
    const response = await fetch('/api/search', {
      method: 'POST',
      body: JSON.stringify({ query: q })
    });

    const data = await response.json();

    // Validate response shape
    const chunks = DocumentChunkSchema.array().parse(data);
    return { chunks };
  },
  component: SearchPage
});

function SearchPage() {
  const { chunks } = Route.useLoaderData();
  // chunks is typed as DocumentChunk[]

  return (
    <div>
      {chunks.map(chunk => (
        <div key={chunk.id}>
          <h3>{chunk.repo}</h3>
          <p>{chunk.content}</p>
        </div>
      ))}
    </div>
  );
}
```

### Maintaining Schema Consistency

**1. Single Source of Truth**
- BAML class definitions are canonical
- All downstream models regenerated from BAML
- Include BAML file in version control
- Generation steps in build/CI pipeline

**2. Automated Generation Workflow**

```json
// package.json
{
  "scripts": {
    "generate": "npm run generate:baml && npm run generate:schemas",
    "generate:baml": "baml-cli generate",
    "generate:schemas": "node scripts/baml-to-zod.js",
    "prebuild": "npm run generate"
  }
}
```

**3. Testing Schema Alignment**

```typescript
// test/schema-alignment.test.ts
import { describe, it, expect } from 'vitest';
import { DocumentChunkSchema } from '~/lib/schemas';
import { DocumentChunk as PydanticDocumentChunk } from '../python/baml_client/types';

describe('Schema Alignment', () => {
  it('should validate Python→TypeScript serialization', () => {
    const pythonData = {
      id: "123",
      repo: "test-repo",
      content: "Test content",
      embedding: [0.1, 0.2, 0.3]
    };

    // Should parse without error
    const parsed = DocumentChunkSchema.parse(pythonData);
    expect(parsed).toEqual(pythonData);
  });
});
```

**4. Versioning Schemas**

Add schema version field for breaking changes:

```baml
class DocumentChunk {
  schema_version int @description("Schema version") @default(1)
  id string
  repo string
  // ... other fields
}
```

Handle migrations:

```typescript
function migrateDocumentChunk(data: any): DocumentChunk {
  if (data.schema_version === 1) {
    return DocumentChunkSchema.parse(data);
  }

  // Handle older versions
  if (!data.schema_version) {
    // Migrate v0 to v1
    return DocumentChunkSchema.parse({
      schema_version: 1,
      ...data,
      // Add new required fields with defaults
    });
  }

  throw new Error(`Unknown schema version: ${data.schema_version}`);
}
```

---

## Real-Time Features

### Chat Interface with Streaming

Implement a responsive chat interface with server-sent streaming and persistent storage.

**Component Implementation:**

```typescript
// src/components/Chat.tsx
import { useState } from 'react';
import { useQuery, useMutation } from 'convex/react';
import { api } from '~/convex/_generated/api';
import { askRepoAI } from '~/server/ai';

function Chat() {
  const [input, setInput] = useState('');
  const [streaming, setStreaming] = useState('');
  const [isStreaming, setIsStreaming] = useState(false);

  // Subscribe to persistent chat history
  const messages = useQuery(api.messages.getAll);
  const saveMessage = useMutation(api.messages.save);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!input.trim() || isStreaming) return;

    const prompt = input;
    setInput('');
    setIsStreaming(true);
    setStreaming('');

    try {
      // Stream response
      const stream = await askRepoAI({ data: { prompt } });
      const reader = stream.body.getReader();
      const decoder = new TextDecoder();

      let fullResponse = '';
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        fullResponse += chunk;
        setStreaming(fullResponse); // Update UI with each token
      }

      // Commit to Convex (triggers sync to all clients)
      await saveMessage({
        prompt,
        response: fullResponse
      });

    } catch (error) {
      console.error('Chat error:', error);
    } finally {
      setIsStreaming(false);
      setStreaming('');
    }
  };

  return (
    <div className="chat-container">
      <div className="messages">
        {messages?.map(msg => (
          <div key={msg._id} className="message">
            <div className="prompt">
              <strong>You:</strong> {msg.prompt}
            </div>
            <div className="response">
              <strong>AI:</strong> {msg.response}
            </div>
          </div>
        ))}

        {/* Show streaming response */}
        {isStreaming && (
          <div className="message streaming">
            <div className="prompt">
              <strong>You:</strong> {input}
            </div>
            <div className="response">
              <strong>AI:</strong> {streaming}
              <span className="cursor">▊</span>
            </div>
          </div>
        )}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          type="text"
          value={input}
          onChange={e => setInput(e.target.value)}
          placeholder="Ask a question..."
          disabled={isStreaming}
        />
        <button type="submit" disabled={isStreaming}>
          {isStreaming ? 'Thinking...' : 'Send'}
        </button>
      </form>
    </div>
  );
}
```

### Live Dashboards with Selective Updates

Display real-time metrics that update only when data changes (no unnecessary polling).

**Data Pipeline:**

```
GitHub Event → DLT/RisingWave → Convex Mutation → WebSocket → UI Update
```

**Convex Schema:**

```typescript
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  github_stats: defineTable({
    orgId: v.string(),
    openIssues: v.number(),
    closedIssues: v.number(),
    openPRs: v.number(),
    lastRelease: v.optional(v.string()),
    updatedAt: v.number()
  }).index("by_org", ["orgId"]),

  sentiment_stats: defineTable({
    orgId: v.string(),
    positiveCount: v.number(),
    negativeCount: v.number(),
    neutralCount: v.number(),
    averageScore: v.number(),
    updatedAt: v.number()
  }).index("by_org", ["orgId"])
});
```

**Convex Mutations (called by pipeline):**

```typescript
// convex/metrics.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const updateGithubStats = mutation({
  args: {
    orgId: v.string(),
    openIssues: v.number(),
    closedIssues: v.number(),
    openPRs: v.number(),
    lastRelease: v.optional(v.string())
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("github_stats")
      .withIndex("by_org", q => q.eq("orgId", args.orgId))
      .first();

    if (existing) {
      await ctx.db.patch(existing._id, {
        ...args,
        updatedAt: Date.now()
      });
    } else {
      await ctx.db.insert("github_stats", {
        ...args,
        updatedAt: Date.now()
      });
    }
  }
});

export const updateSentimentStats = mutation({
  args: {
    orgId: v.string(),
    positiveCount: v.number(),
    negativeCount: v.number(),
    neutralCount: v.number(),
    averageScore: v.number()
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("sentiment_stats")
      .withIndex("by_org", q => q.eq("orgId", args.orgId))
      .first();

    if (existing) {
      await ctx.db.patch(existing._id, {
        ...args,
        updatedAt: Date.now()
      });
    } else {
      await ctx.db.insert("sentiment_stats", {
        ...args,
        updatedAt: Date.now()
      });
    }
  }
});
```

**Convex Queries:**

```typescript
// convex/metrics.ts
import { query } from "./_generated/server";
import { v } from "convex/values";

export const getGithubStats = query({
  args: { orgId: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("github_stats")
      .withIndex("by_org", q => q.eq("orgId", args.orgId))
      .first();
  }
});

export const getSentimentStats = query({
  args: { orgId: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("sentiment_stats")
      .withIndex("by_org", q => q.eq("orgId", args.orgId))
      .first();
  }
});
```

**React Component:**

```typescript
// src/components/LiveDashboard.tsx
import { useQuery } from 'convex/react';
import { api } from '~/convex/_generated/api';

function LiveDashboard({ orgId }: { orgId: string }) {
  // Automatically updates when data changes
  const githubStats = useQuery(api.metrics.getGithubStats, { orgId });
  const sentimentStats = useQuery(api.metrics.getSentimentStats, { orgId });

  if (!githubStats || !sentimentStats) {
    return <div>Loading...</div>;
  }

  return (
    <div className="dashboard">
      <div className="card">
        <h2>GitHub Activity</h2>
        <div className="stats">
          <div>
            <span className="label">Open Issues</span>
            <span className="value">{githubStats.openIssues}</span>
          </div>
          <div>
            <span className="label">Open PRs</span>
            <span className="value">{githubStats.openPRs}</span>
          </div>
          <div>
            <span className="label">Latest Release</span>
            <span className="value">{githubStats.lastRelease || 'None'}</span>
          </div>
        </div>
      </div>

      <div className="card">
        <h2>Social Sentiment</h2>
        <div className="sentiment-score">
          <div className="score" style={{
            color: sentimentStats.averageScore > 0.5 ? 'green' : 'red'
          }}>
            {(sentimentStats.averageScore * 100).toFixed(1)}%
          </div>
          <div className="breakdown">
            <span>👍 {sentimentStats.positiveCount}</span>
            <span>😐 {sentimentStats.neutralCount}</span>
            <span>👎 {sentimentStats.negativeCount}</span>
          </div>
        </div>
      </div>
    </div>
  );
}
```

**Key Benefits:**
- **No polling** – Updates pushed via WebSocket when data changes
- **Efficient** – Only changed data transmitted
- **Consistent** – All clients see same state
- **Simple** – No manual subscription management

### Collaboration and Presence

Implement real-time collaboration features using Convex's presence component.

**Installation:**

```bash
npm install @convex-dev/presence
```

**Setup:**

```typescript
// convex/presence.ts
import { Presence } from "@convex-dev/presence/Presence";

const presence = new Presence();
export default presence;
```

**Component Usage:**

```typescript
// src/components/CollaboratorPresence.tsx
import { usePresence } from '@convex-dev/react';
import presence from '~/convex/presence';

function CollaboratorPresence({ roomId }: { roomId: string }) {
  const { myPresence, othersPresence } = usePresence(presence, roomId);

  return (
    <div className="presence">
      <div className="presence-indicator">
        {othersPresence.length > 0 && (
          <div className="avatars">
            {othersPresence.map(user => (
              <img
                key={user.id}
                src={user.avatar}
                alt={user.name}
                title={user.name}
                className="avatar"
              />
            ))}
          </div>
        )}
        <span className="count">
          {othersPresence.length === 0
            ? 'Only you'
            : `${othersPresence.length + 1} viewing`}
        </span>
      </div>
    </div>
  );
}
```

---

## Deployment

### Cloudflare Workers/Pages Configuration

Deploy TanStack Start applications to Cloudflare for global edge distribution.

**Vite Configuration:**

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { tanstackStart } from '@tanstack/start/vite';

export default defineConfig({
  plugins: [
    react(),
    tanstackStart({
      adapter: 'cloudflare-pages'
    })
  ],
  build: {
    target: 'esnext'
  }
});
```

**wrangler.toml:**

```toml
name = "my-tanstack-app"
compatibility_date = "2024-01-01"
pages_build_output_dir = "dist"

[env.production]
vars = { NODE_ENV = "production" }

[[env.production.kv_namespaces]]
binding = "KV"
id = "your-kv-namespace-id"
```

**Deployment:**

```bash
# Build
npm run build

# Deploy to Cloudflare Pages
npx wrangler pages deploy dist
```

**Environment Variables (Cloudflare Dashboard):**

```
BETTER_AUTH_SECRET=xxx
CONVEX_URL=https://xxx.convex.cloud
DATABASE_URL=postgresql://...
```

### Netlify as Alternative

**netlify.toml:**

```toml
[build]
  command = "npm run build"
  publish = "dist"
  functions = "netlify/functions"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[functions]
  node_bundler = "esbuild"
  directory = "netlify/functions"
```

**Vite Configuration:**

```typescript
// vite.config.ts
export default defineConfig({
  plugins: [
    react(),
    tanstackStart({
      adapter: 'netlify'
    })
  ]
});
```

**Deployment:**

```bash
# Install Netlify CLI
npm install -g netlify-cli

# Login
netlify login

# Deploy
netlify deploy --prod
```

### Environment Variables and Secrets

**Best Practices:**

1. **Never commit secrets to Git**
   ```gitignore
   # .gitignore
   .env
   .env.local
   .env.*.local
   ```

2. **Use platform-specific secret management**
   - Cloudflare: Wrangler secrets or dashboard
   - Netlify: Environment variables dashboard
   - Docker: Environment files or Docker secrets

3. **Separate by environment**
   ```
   .env.development    # Local development
   .env.staging        # Staging environment
   .env.production     # Production (never committed)
   ```

4. **Type-safe environment variables**

```typescript
// src/lib/env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  BETTER_AUTH_SECRET: z.string().min(32),
  DATABASE_URL: z.string().url(),
  CONVEX_URL: z.string().url(),
  SENTRY_DSN: z.string().optional(),
  OPENAI_API_KEY: z.string().optional()
});

export const env = envSchema.parse(process.env);
```

### CI/CD Patterns

**GitHub Actions Example:**

```yaml
# .github/workflows/deploy.yml
name: Deploy

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm test

  deploy-staging:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build
        env:
          BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET_STAGING }}
          DATABASE_URL: ${{ secrets.DATABASE_URL_STAGING }}
          CONVEX_URL: ${{ secrets.CONVEX_URL_STAGING }}

      - name: Deploy to Netlify Staging
        run: npx netlify deploy --dir=dist
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID_STAGING }}

  deploy-production:
    needs: test
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build
        env:
          NODE_ENV: production
          BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET_PROD }}
          DATABASE_URL: ${{ secrets.DATABASE_URL_PROD }}
          CONVEX_URL: ${{ secrets.CONVEX_URL_PROD }}

      - name: Deploy to Cloudflare Pages
        run: npx wrangler pages deploy dist
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
```

---

## Observability

### Sentry Integration

Full-stack error monitoring with TanStack Start.

**Installation:**

```bash
npm install @sentry/tanstackstart-react
```

**Client-Side Setup:**

```typescript
// src/entry-client.tsx
import * as Sentry from '@sentry/tanstackstart-react';
import { router } from './router';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  integrations: [
    Sentry.tanstackRouterBrowserTracingIntegration(router),
    Sentry.replayIntegration()
  ],
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0
});
```

**Server-Side Setup:**

```typescript
// src/entry-server.tsx
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0
});
```

**Error Boundary:**

```typescript
// src/components/ErrorBoundary.tsx
import * as Sentry from '@sentry/tanstackstart-react';

export function ErrorBoundary({ children }: { children: React.ReactNode }) {
  return (
    <Sentry.ErrorBoundary
      fallback={({ error, resetError }) => (
        <div className="error-page">
          <h1>Something went wrong</h1>
          <p>{error.message}</p>
          <button onClick={resetError}>Try again</button>
        </div>
      )}
      showDialog
    >
      {children}
    </Sentry.ErrorBoundary>
  );
}
```

**Custom Error Tracking:**

```typescript
import * as Sentry from '@sentry/tanstackstart-react';

try {
  await riskyOperation();
} catch (error) {
  Sentry.captureException(error, {
    tags: { operation: 'riskyOperation' },
    extra: { userId: user.id }
  });
  throw error;
}
```

### Usage Tracking with Autumn

Track API usage and enforce limits/billing.

**Installation:**

```bash
npm install autumn-js
```

**Frontend Setup:**

```typescript
// src/lib/autumn.tsx
import { AutumnProvider } from 'autumn-js/react';

export function AutumnClientProvider({ children }: { children: React.ReactNode }) {
  return (
    <AutumnProvider apiKey={import.meta.env.VITE_AUTUMN_PUBLIC_KEY}>
      {children}
    </AutumnProvider>
  );
}
```

**Backend Tracking:**

```typescript
// src/server/ai.ts
import { Autumn } from 'autumn-js';

const autumn = new Autumn({
  secretKey: process.env.AUTUMN_SECRET_KEY
});

export const askRepoAI = createServerFn({ method: 'POST' })
  .handler(async function* ({ data, context }) {
    const { prompt } = data;
    const user = context.user;

    // Check if user has quota
    const canProceed = await autumn.check({
      customerId: user.id,
      featureId: 'ai_query'
    });

    if (!canProceed) {
      throw new Error('Usage limit reached');
    }

    // Stream response...
    for await (const chunk of aiStream) {
      yield chunk;
    }

    // Track usage after success
    await autumn.track({
      customerId: user.id,
      featureId: 'ai_query',
      value: 1
    });
  });
```

**Frontend Usage Display:**

```typescript
// src/components/UsageIndicator.tsx
import { useCustomer } from 'autumn-js/react';

function UsageIndicator() {
  const customer = useCustomer();

  if (!customer) return null;

  const usage = customer.usage['ai_query'];
  const limit = customer.plan.features['ai_query'].limit;

  return (
    <div className="usage-indicator">
      <span>AI Queries: {usage} / {limit}</span>
      <progress value={usage} max={limit} />
    </div>
  );
}
```

---

## Best Practices & Patterns

### When to Use Streaming vs Selective Updates

| Use Case | Approach | Reasoning |
|----------|----------|-----------|
| **AI Text Generation** | Server Streaming | Continuous output, immediate feedback needed |
| **Chat Messages** | Selective Updates (Convex) | Discrete events, need persistence |
| **Dashboard Metrics** | Selective Updates (Convex) | Infrequent changes, need consistency |
| **Live Activity Feed** | Selective Updates (Convex) | Event-driven, multiple consumers |
| **File Upload Progress** | Server Streaming | Continuous percentage updates |
| **Real-Time Collaboration** | Selective Updates (Convex) | Shared state across clients |

**Decision Matrix:**

```
Is content generated incrementally? → YES → Use Streaming
                                    ↓ NO
Is data shared across multiple users? → YES → Use Convex
                                         ↓ NO
Is data ephemeral (not persisted)? → YES → Use Streaming
                                     ↓ NO
                              Use Convex
```

### Server vs Client Data Fetching

**Fetch on Server When:**
- Initial page load (SSR)
- Data requires authentication
- Sensitive API keys involved
- SEO important
- Reduce client bundle size

```typescript
// ✅ Server-side
export const Route = createFileRoute('/dashboard')({
  loader: () => getInitialDashboardStats(), // Server function
  component: Dashboard
});
```

**Fetch on Client When:**
- User interaction triggers fetch
- Data updates frequently
- Optimistic updates needed
- Progressive enhancement

```typescript
// ✅ Client-side
function Dashboard() {
  const stats = useQuery(api.stats.get); // Convex query
  return <div>{stats?.value}</div>;
}
```

**Hybrid Approach (Best Practice):**

```typescript
// Server: Initial load
export const Route = createFileRoute('/dashboard')({
  loader: () => getInitialStats(),
  component: Dashboard
});

// Client: Real-time updates
function Dashboard() {
  const initialStats = Route.useLoaderData();
  const liveStats = useQuery(api.stats.get); // Overrides initial

  const stats = liveStats ?? initialStats; // Fallback pattern
  return <div>{stats.value}</div>;
}
```

### Security Considerations

**1. Authentication at Every Layer**

```typescript
// Server Function
export const secureOperation = createServerFn()
  .middleware(async ({ context, next }) => {
    const user = await getAuthenticatedUser(context);
    if (!user) throw new Error('Unauthorized');
    return next({ context: { ...context, user } });
  })
  .handler(async ({ context }) => {
    // context.user is guaranteed to exist
    return performOperation(context.user);
  });
```

**2. Input Validation**

```typescript
// Always validate untrusted input
import { z } from 'zod';

const inputSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150)
});

export const createUser = createServerFn({ method: 'POST' })
  .handler(async ({ data }) => {
    const validated = inputSchema.parse(data); // Throws on invalid
    return db.users.create(validated);
  });
```

**3. CORS Configuration**

```typescript
// Hono
import { cors } from 'hono/cors';

app.use('/api/*', cors({
  origin: ['http://localhost:3000', 'https://app.example.com'],
  credentials: true
}));
```

**4. Rate Limiting**

```typescript
// Using rate limiter
import { RateLimiter } from 'limiter';

const limiter = new RateLimiter({
  tokensPerInterval: 100,
  interval: 'minute'
});

export const apiEndpoint = createServerFn()
  .middleware(async ({ context, next }) => {
    const remaining = await limiter.removeTokens(1);
    if (remaining < 0) {
      throw new Error('Rate limit exceeded');
    }
    return next();
  })
  .handler(async () => {
    // Protected by rate limiter
  });
```

**5. SQL Injection Prevention**

```typescript
// ✅ Parameterized queries
const users = await db.query(
  'SELECT * FROM users WHERE email = $1',
  [email]
);

// ❌ String concatenation (vulnerable)
const users = await db.query(
  `SELECT * FROM users WHERE email = '${email}'`
);
```

**6. XSS Prevention**

```typescript
// React automatically escapes content
<div>{userInput}</div> // Safe

// Dangerous: dangerouslySetInnerHTML
<div dangerouslySetInnerHTML={{ __html: userInput }} /> // ❌

// Use DOMPurify for HTML content
import DOMPurify from 'dompurify';
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userInput) }} /> // ✅
```

### Performance Optimization

**1. Code Splitting**

```typescript
// Route-level splitting (automatic with TanStack Router)
const DashboardRoute = createFileRoute('/dashboard')({
  component: () => import('./Dashboard').then(m => m.Dashboard)
});

// Component-level splitting
const HeavyComponent = lazy(() => import('./HeavyComponent'));
```

**2. Memoization**

```typescript
import { useMemo } from 'react';

function ExpensiveComponent({ data }: { data: Item[] }) {
  const processed = useMemo(() => {
    return data.map(item => expensiveTransform(item));
  }, [data]); // Only recompute when data changes

  return <div>{processed}</div>;
}
```

**3. Virtualization**

```typescript
import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50
  });

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px` }}>
        {virtualizer.getVirtualItems().map(virtualRow => (
          <div
            key={virtualRow.index}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              transform: `translateY(${virtualRow.start}px)`
            }}
          >
            {items[virtualRow.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}
```

**4. Database Indexing**

```typescript
// Convex schema with indexes
export default defineSchema({
  users: defineTable({
    email: v.string(),
    orgId: v.string(),
    createdAt: v.number()
  })
    .index("by_email", ["email"])
    .index("by_org", ["orgId"])
    .index("by_org_created", ["orgId", "createdAt"])
});
```

### Error Handling Patterns

**1. Global Error Boundary**

```typescript
// src/App.tsx
import { ErrorBoundary } from './components/ErrorBoundary';

function App() {
  return (
    <ErrorBoundary>
      <Router />
    </ErrorBoundary>
  );
}
```

**2. Try-Catch with User Feedback**

```typescript
async function handleSubmit() {
  setLoading(true);
  setError(null);

  try {
    await submitForm(data);
    toast.success('Submitted successfully');
  } catch (error) {
    if (error instanceof ValidationError) {
      setError(error.message);
    } else {
      toast.error('An unexpected error occurred');
      Sentry.captureException(error);
    }
  } finally {
    setLoading(false);
  }
}
```

**3. Retry Logic**

```typescript
async function fetchWithRetry(url: string, retries = 3): Promise<Response> {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return response;

      if (response.status >= 500) {
        // Server error, retry
        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
        continue;
      }

      // Client error, don't retry
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
    }
  }

  throw new Error('Max retries exceeded');
}
```

---

## Conclusion

This architecture provides a comprehensive foundation for building modern, type-safe, real-time web applications. Key takeaways:

**✅ Unified Type System** – BAML → Pydantic + Zod ensures consistency across the stack

**✅ Real-Time by Default** – Convex provides automatic synchronization without polling

**✅ Secure Authentication** – BetterAuth with OIDC supports multi-tenancy and self-hosting

**✅ Flexible Deployment** – Deploy to Cloudflare, Netlify, or any edge platform

**✅ Developer Experience** – TypeScript end-to-end with excellent tooling

**✅ Production Ready** – Built-in observability, error tracking, and usage monitoring

This stack balances cutting-edge technology with proven patterns, enabling teams to ship features quickly while maintaining high code quality and system reliability.

---

## Additional Resources

### Documentation
- [TanStack Start](https://tanstack.com/start)
- [Convex](https://docs.convex.dev/)
- [BetterAuth](https://www.better-auth.com/docs)
- [BAML](https://docs.boundaryml.com/)
- [Zod](https://zod.dev/)

### Templates
- [Better-T-Stack](https://github.com/AmanVarshney01/Better-T-Stack)
- [TanStack Start Examples](https://github.com/tanstack/start/tree/main/examples)
- [Convex Templates](https://www.convex.dev/templates)

### Community
- [TanStack Discord](https://discord.gg/tanstack)
- [Convex Discord](https://discord.gg/convex)
- [BetterAuth Discord](https://discord.gg/better-auth)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall