Monorepo Architecture Overview

Repository Layout


OpenTier/
├── client/
│   ├── package.json          # Turborepo workspace root
│   ├── turbo.json            # Pipeline definitions
│   ├── web/                  # Next.js 16 application
│   │   ├── app/              # App Router pages
│   │   ├── components/       # UI, AI elements, core modules
│   │   ├── context/          # React context providers
│   │   ├── store/            # Zustand state stores
│   │   ├── lib/              # API client, type schemas
│   │   ├── hooks/            # Custom React hooks
│   │   └── types/            # Shared TypeScript types
│   └── docs/                 # Documentation content (MDX)
│
└── server/
    ├── docker-compose.yml    # Orchestrates db → migrations → services
    ├── .env                  # Database credentials (POSTGRES_USER, etc.)
    ├── api/                  # Rust/Axum API gateway (Cargo workspace)
    │   ├── src/              # Service source modules
    │   └── .sqlx/            # Offline query cache (CI safety)
    ├── db/                   # Unified database management
    │   └── migrations/       # All SQL migrations (up/down)
    ├── intelligence/         # Python gRPC intelligence engine
    │   ├── core/             # Config, DB session, lifecycle
    │   ├── engine/           # Business logic (chat, ingestion, retrieval)
    │   └── interfaces/       # gRPC servicers
    └── proto/
        └── intelligence.proto # Shared Protobuf contract

Isolation Boundaries

Language Boundaries

Boundary	Mechanism	Protocol	Schema enforcement
Browser ↔ Next.js	Fetch API + SSE	HTTP/1.1	Zod (`api-types.ts`)
Next.js ↔ Rust API	HTTP Proxy (`next.config`)	HTTP/1.1	None (passthrough)
Rust ↔ Python	tonic client / grpcio server	HTTP/2 gRPC	Protobuf v3
Rust ↔ PostgreSQL	sqlx (offline-verified)	TCP	Compile-time query checks
Python ↔ PostgreSQL	asyncpg / SQLAlchemy	TCP	SQLAlchemy ORM models

Deployment Implications

Three independent processes: client (Node/Bun), API (Rust binary), Intelligence (Python). Each can be scaled, restarted, and deployed independently.
Single database: both Rust and Python connect to the same PostgreSQL instance. All migrations are centralized in server/db/migrations/ and managed by sqlx-cli.
Orchestrated startup: Docker Compose enforces the startup order: db (healthcheck) → api & intelligence. The api container applies any pending SQL migrations, prepares the sqlx cache dynamically, and builds at runtime sequentially.
Port assignments: API default 4000, Intelligence gRPC default 50051 (configurable via INTELLIGENCE_SERVICE_URL).
gRPC lazy connect: if the Intelligence service is down, the Rust API boots successfully (with degraded chat functionality). Auth, user, and admin endpoints remain fully operational.
Runtime sqlx preparation: Rust sqlx queries are built at runtime in the API Docker container when the database is available. This enables SQL types to be rigorously database-checked automatically on docker compose start, ensuring the db matches the API schemas without tracking offline cache files.