Cosmo (WunderGraph)

# MISSION: Scaffold "Cosmo (WunderGraph)" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Cosmo (WunderGraph)**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Cosmo (WunderGraph)
- **What It Does**: WunderGraph Cosmo is an open-source GraphQL Federation platform providing a schema registry, composition checks, analytics, and a runtime router for building and operating federated GraphQL APIs on-prem or as a managed service.
- **Domain & Category**: Federated GraphQL API Gateway
- **Production Scale**: 6-20 People
- **Development Mode**: HYBRID
- **Architectural Rationale**: Splitting the Go router (runtime query execution) from the TypeScript Controlplane (schema registry and management) lets Cosmo scale and deploy the performance-critical data path independently, while a dedicated ClickHouse-backed metrics service keeps high-volume usage analytics off the primary Postgres database.
- **Live Website Reference**: https://wundergraph.com/cosmo
- **Source Repository**: https://github.com/wundergraph/cosmo
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Go, PostgreSQL, ClickHouse, Drizzle, Keycloak, ConnectRPC, Next.js, NATS, Protocol Buffers, Helm, Docker
- **Primary Language(s)**: TypeScript, Go, HTML
- **License of the reference repo**: Apache-2.0
- **Frontend**: Next.js — Powers the Studio web app used to manage federated graphs, schema checks, and analytics.; Radix UI — Provides headless UI primitives (dialog, dropdown, accordion, popover) for the Studio interface.; GraphiQL — Embedded GraphQL IDE for exploring federated schemas, included at the workspace root.
- **Backend & APIs**: TypeScript — Implements the Controlplane API, CLI (wgc), CDN server, and graphqlmetrics ingestion service.; Go — Implements the Cosmo Router, the GraphQL federation gateway that serves runtime traffic.; ConnectRPC — RPC framework used between the CLI, Studio, and Controlplane, generated from Protobuf definitions.
- **Data & persistence**: PostgreSQL — System of record for the Controlplane (organizations, graphs, schema versions), managed with Drizzle.; Drizzle — ORM and migration tool for the Controlplane Postgres schema, driven by drizzle-kit generate/check.; ClickHouse — Stores GraphQL usage metrics and traces ingested by the graphqlmetrics service, migrated via dbmate.
- **Infrastructure & deploy**: Keycloak — Handles authentication and organization/user management for the platform, run as its own service.; Docker — Every service (controlplane, router, cdn-server, graphqlmetrics, keycloak) ships its own Dockerfile.; Helm — Official Helm charts deploy the full platform to Kubernetes, released through dedicated CI workflows.; NATS — Event-driven subscriptions and federated GraphQL subscription delivery, per the project blog posts.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/wundergraph/cosmo @ 26545dc)
1. **The platform is a pnpm/Turborepo-style monorepo split across TypeScript and Go workspaces**: pnpm-workspace.yaml lists controlplane, cli, studio, router, router-plugin, cdn-server, graphqlmetrics, connect, protographic, and more as independent packages, while router, aws-lambda-router, connect-go, demo, and graphqlmetrics ship their own go.mod files for the Go-based components.
2. **Runtime traffic and control-plane management are separate services in separate languages**: The Cosmo Router (router/package.json, a Go binary) handles live federated GraphQL query execution, while the Controlplane (controlplane/package.json, TypeScript) handles schema registry, composition checks, and organization management, so router performance is not coupled to the Node.js control-plane runtime.
3. **The Controlplane schema is managed with Drizzle, not Prisma or raw SQL**: controlplane/package.json defines db:generate, db:check, and db:drop scripts around drizzle-kit against drizzle.config.ts, giving the TypeScript control-plane typed, code-first Postgres migrations.
4. **Usage analytics run through a dedicated Go service writing to ClickHouse**: graphqlmetrics/go.mod depends on github.com/ClickHouse/clickhouse-go/v2 and github.com/amacneil/dbmate/v2, and the controlplane package.json exposes a separate ch:migrate script (pnpm ch:migrate) alongside its Postgres db:migrate script, keeping the high-volume metrics path off the primary OLTP database.
5. **Auth is delegated to Keycloak rather than a custom identity system**: docker-compose.yml runs a keycloak service built from the keycloak/ directory (with its own Dockerfile) that imports a preconfigured realm.json, and the Controlplane is configured with KC_DB_URL_HOST pointing at the same Postgres instance used for application data.
6. **Inter-service RPC uses ConnectRPC over Protobuf instead of plain REST or GraphQL**: The root package.json generate script runs pnpm buf generate against proto/wg/cosmo/platform, proto/wg/cosmo/notifications, proto/wg/cosmo/common, and proto/wg/cosmo/node, and graphqlmetrics/go.mod depends on connectrpc.com/connect, so the CLI, Studio, and Controlplane share generated, typed clients.
7. **The CLI (wgc) can build as a TypeScript/Node tool or a standalone compiled binary**: cli/package.json defines both a build script (tsc, for npm distribution) and a build:bun script (bun build --compile --production --outfile wgc), giving users either an npm-installed CLI or a single native executable.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, Drizzle, ClickHouse): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.