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 database, redis, qdrant, intelligence, worker, api
    ├── .env                  # Database credentials (POSTGRES_USER, ENCRYPTION_MASTER_KEY, etc.)
    ├── api/                  # Rust/Axum API gateway (Cargo workspace)
    │   ├── src/              # Service source modules (auth, chat, admin, resources)
    │   ├── migrations/       # All SQL migrations (up/down)
    │   └── .sqlx/            # Offline query cache (CI safety)
    ├── intelligence/         # Python gRPC intelligence engine & workers
    │   ├── core/             # Config, DB session, lifecycle, events
    │   ├── features/         # Chat, knowledge, billing, and auth
    │   ├── shared/qdrant/    # Qdrant hybrid vector store adapter (dense + sparse)
    │   ├── shared/redis/     # Redis Streams bus, consumer groups, dedupe
    │   ├── scripts/          # DLQ management, backfill, and smoke tests
    │   └── worker.py         # Autonomous background stream consumer runtime
    └── 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 (`intelligence.proto`)
Rust ↔ Redis	redis-rs	RESP3 / TCP	Redis command protocol
Python ↔ Redis	redis.asyncio	RESP3 / TCP	`EventEnvelope` (`core.events`)
Python ↔ Qdrant	qdrant-client	HTTP/REST & gRPC	Qdrant point schema (`knowledge_chunks`)
Rust ↔ PostgreSQL	sqlx (compile-time checked)	TCP	Compile-time query checks
Python ↔ PostgreSQL	asyncpg / SQLAlchemy	TCP	SQLAlchemy ORM models

Deployment Implications

Decoupled Architecture: Six containerized services (api, intelligence, worker, qdrant, redis, database) orchestrated via Docker Compose.
Independent Failure Domains: If background ingestion or high-volume scraping is under heavy load, the worker process absorbs the work without degrading the gRPC intelligence engine or the Rust api gateway.
Dedicated Vector Store: Qdrant handles all high-dimensional dense vectors and sparse lexical indices with sub-millisecond HNSW matching, offloading vector computations from PostgreSQL.
Event Bus with Durability: Redis 8 with AOF persistence ensures task events are queued safely with consumer groups, manual acknowledgment (XACK), automatic reclamation of abandoned tasks (XAUTOCLAIM), and Dead-Letter Queues (DLQ).
Port assignments: API 4000, Intelligence gRPC 50051, Qdrant 6333/6334, Redis 6379, PostgreSQL 5432.
Runtime sqlx preparation: Rust sqlx queries are built dynamically in the API Docker container against the healthy PostgreSQL database.