Skip to content

Developer Workflow (Pydantic → TypeScript → UI)

  • Hard Rules

    Pydantic first. No adapters. No hand-written API types.

  • Generated Types

    uv run scripts/generate_types.py produces generated.ts.

  • Clean Flow

    models → stores → hooks → components.

Get started Configuration API

Single Source of Truth

All configurable parameters and data shapes live in server/models/tribrid_config_model.py.

Validate Sync

Run uv run scripts/validate_types.py to confirm generated types match Pydantic.

Banned Patterns

  • Hand-written interfaces for API payloads
  • *Adapter, *Transformer, *Mapper classes to reshape payloads

Derivation Chain

flowchart TB
    P["Pydantic"] --> G["generate_types.py"]
    G --> T["web/src/types/generated.ts"]
    T --> S["Zustand Stores"]
    S --> H["React Hooks"]
    H --> C["Components"]

Commands

  • uv run scripts/generate_types.py (after ANY Pydantic change)
  • uv run scripts/validate_types.py (CI/verify before commit)
  • uv run scripts/check_banned.py (guardrails)
import subprocess
subprocess.check_call(["uv", "run", "scripts/generate_types.py"])  # (1)!
subprocess.check_call(["uv", "run", "scripts/validate_types.py"])  # (2)!

# No curl for local codegen; use uv-run commands

// Use generated types only
import type { SearchRequest } from "../types/generated"; // (3)!
  1. Generate TS types from Pydantic
  2. Validate that TS matches server models
  3. Client code imports generated types

Directory Purposes

Path Purpose
server/models/tribrid_config_model.py Pydantic models — THE LAW
web/src/types/generated.ts Auto-generated API types
web/src/stores/*.ts Zustand stores using generated types
web/src/hooks/*.ts React hooks wrapping stores
web/src/components/**/*.tsx Components consuming hooks
Ralph Loop

Use the recommended loop to implement TODOs end-to-end with verification: validators, tests, and Stop hook enforcement.