Hasura

# MISSION: Scaffold "Hasura" 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 **Hasura**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Hasura
- **What It Does**: Hasura is an open-source engine that turns a database schema into a secured, realtime GraphQL and REST API, shipping two parallel engines from one repository: a mature Haskell server for GraphQL Engine V2 and a newer Rust engine powering Hasura DDN (V3).
- **Domain & Category**: Instant GraphQL Engine & Unified Data Access
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Hasura runs two independently evolving query engines from one repository — a Haskell V2 server and a Rust V3 engine — and extends database support through an out-of-process Data Connector protocol, so a new database backend plugs in as a separate agent instead of new code inside either engine.
- **Live Website Reference**: https://hasura.io
- **Source Repository**: https://github.com/hasura/graphql-engine
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Haskell, Rust, Go, GraphQL, PostgreSQL, React, SQLite, Docker
- **Primary Language(s)**: TypeScript, Haskell
- **License of the reference repo**: Apache-2.0
- **Frontend**: React — The Hasura Console (frontend/) is an Nx-managed React workspace, pinned to React 17 via a yarn resolution.
- **Backend & APIs**: Haskell — GraphQL Engine V2 server lives in server/ as a Cabal project (graphql-engine.cabal), the mature production engine.; Rust — GraphQL Engine V3, powering Hasura DDN, lives in v3/ as a Cargo workspace of engine/execute/plan/metadata-resolve crates.; Go — The hasura CLI (cli/, module github.com/hasura/graphql-engine/cli/v2) is a separate Go binary from both engines.; GraphQL — The query language both the V2 Haskell engine and V3 Rust engine expose over the database schema.
- **Data & persistence**: PostgreSQL — Primary supported database; CircleCI test images build Postgres with PostGIS for geospatial query coverage.; SQLite — Reference Data Connector agent (dc-agents/sqlite) shows how a new database backend plugs in without engine changes.
- **Infrastructure & deploy**: Docker — packaging/graphql-engine/Dockerfile builds the release server image; docker-compose.yaml and dc-agents/*/Dockerfile cover local/dev stacks.; CircleCI — Primary CI for the V2 Haskell server and console (.circleci/config.yml, per-database test Docker images).
- **Tooling, testing & ops**: Cabal — Build system and dependency resolver for the Haskell V2 server (cabal.project, multiple dev/CI project variants).; HLint — Haskell linter run in CI for the V2 server, configured via .hlint.yaml and the hlint.yml workflow.; Vitest — Unit test runner for cli-ext, the standalone action-scaffolding service (test:unit script).
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/hasura/graphql-engine @ 17493b6)
1. **Two GraphQL engines, Haskell V2 and Rust V3, ship from one repository**: server/graphql-engine.cabal builds the mature, Haskell-based GraphQL Engine V2, while v3/Cargo.toml defines a separate Rust workspace (package.version = "3.0.0") powering Hasura DDN; the README documents both under distinct "Hasura V2" and "Hasura V3" sections rather than treating V3 as a simple upgrade of V2.
2. **New databases plug in as out-of-process Data Connector agents**: dc-agents/reference (a Node/TypeScript template, exposing port 8100) and dc-agents/sqlite (@hasura/dc-agent-sqlite) both implement the same dc-api-types contract from dc-agents/dc-api-types/package.json, so adding database support does not require changing the Haskell or Rust engine code, only writing a new agent against the documented protocol.
3. **The CLI is a standalone Go module, not part of either engine**: cli/go.mod declares module github.com/hasura/graphql-engine/cli/v2 as its own Go module with its own dependency set (including gin-gonic/gin and gin-contrib/static to serve the local console UI), built and released independently of the server/ (Haskell) and v3/ (Rust) engines.
4. **V3 engine crates are split by query pipeline stage, not by connector**: v3/Cargo.toml workspace members include engine, execute, plan, plan-types, metadata-resolve, jsonapi, compatibility, open-dds, plus glob groups graphql/* and auth/*, mirroring the path a query takes from metadata resolution through planning to execution rather than grouping code by which external database or connector it targets.
5. **Postgres with PostGIS is the pinned reference test database for V2**: .circleci/postgres-12.0-alpine-postgis3/Dockerfile and .circleci/postgres-13.0-alpine-postgis3/Dockerfile both build from circleci/postgres:<version>-postgis rather than the plain Postgres image, so CI exercises geospatial (PostGIS) query support as a standard part of the V2 test matrix.
6. **The Console frontend and the Action-scaffolding service are separate JS/TS projects**: frontend/package.json (Nx workspace, React 17 pinned via a yarn resolution) builds the Console UI, while cli-ext/package.json (name scaffolder, Babel-transpiled) is an independent Node service the CLI calls out to for generating Hasura Action scaffolds, each with its own dependency tree, build and test setup.
---
## 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**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
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, SQLite): 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.