NocoDB

# MISSION: Scaffold "NocoDB" 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 **NocoDB**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: NocoDB
- **What It Does**: NocoDB is a self-hostable, open-source Airtable alternative built as a TypeScript pnpm monorepo, pairing a NestJS and Knex backend that supports PostgreSQL, MySQL, and SQLite with a Nuxt-based Vue frontend for spreadsheet-style database views.
- **Domain & Category**: Smart Database Spreadsheet
- **Production Scale**: 6-20 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: The backend uses Knex as a database-agnostic query layer over pg, mysql2, and sqlite3 so the same NestJS service can target whichever database an operator already runs, while the frontend and SDK are separate workspace packages that let the grid UI and API client evolve without redeploying the whole app.
- **Live Website Reference**: https://nocodb.com
- **Source Repository**: https://github.com/nocodb/nocodb
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Vue, Nuxt, NestJS, PostgreSQL, MySQL, SQLite, Redis, Socket.IO, Docker
- **Primary Language(s)**: TypeScript, Vue, JavaScript
- **License of the reference repo**: NOASSERTION
- **Frontend**: Vue — Implements the nc-gui grid, form, and kanban view components.; Nuxt — Application framework wrapping the Vue frontend in packages/nc-gui.; Vercel AI SDK — Powers AI-assisted features in the frontend via the ai package and provider adapters.
- **Backend & APIs**: NestJS — Structures the nocodb backend service (controllers, modules, DI) in packages/nocodb.; Vercel AI SDK — Backend AI SDK integrations (@ai-sdk/openai, @ai-sdk/anthropic, and others) for AI-powered fields and automations.; Socket.IO — Provides realtime updates between the NestJS backend and connected clients.
- **Data & persistence**: PostgreSQL — Supported external database backend, connected through the pg driver.; MySQL — Supported external database backend, connected through the mysql2 driver.; SQLite — Default embedded database for the Docker quick-start and local development.; Redis — Used for caching and throttler storage via nest-lab and ioredis.
- **Infrastructure & deploy**: Docker — Documented as the primary self-hosting method, including a SQLite-only quick-start image.; pnpm — Package manager for the workspace, enforced via a preinstall guard.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/nocodb/nocodb @ b2f7e0f)
1. **Backend is a NestJS service with pluggable SQL drivers via Knex**: packages/nocodb/package.json depends on @nestjs/core, @nestjs/common, and @nestjs/platform-express for the application structure, and on knex plus pg, mysql2, and sqlite3 as swappable database drivers, so the same backend targets Postgres, MySQL, or SQLite.
2. **Frontend is a Nuxt application, not a plain Vue SPA**: packages/nc-gui/package.json runs on nuxt dev and nuxt prepare (postinstall) rather than a bare Vite/Vue setup, and pulls in UnoCSS and ant-design-vue for styling and components alongside the custom grid and view UI.
3. **BullMQ-family queueing and Redis-backed throttling handle background work**: packages/nocodb/package.json lists bull for job queues and @nest-lab/throttler-storage-redis plus ioredis for rate limiting and caching, separating long-running import/export and automation jobs from the request/response cycle.
4. **AI provider access goes through the Vercel AI SDK, not direct provider clients**: packages/nocodb/package.json depends on the ai package plus @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, @ai-sdk/azure, and other @ai-sdk/* adapters, giving AI-powered fields a single abstraction over multiple LLM providers.
5. **The SDK is a separate published package consumed by both frontend and backend**: packages/nocodb-sdk/package.json builds a standalone nocodb-sdk package (generated in part from a Swagger spec via swagger-typescript-api) that packages/nc-gui and packages/nocodb both depend on as a workspace package, keeping the API client in sync with the server.
6. **Self-hosting is supported on Docker, DigitalOcean, and Helm/Kubernetes**: The repository ships a .do/deploy.template.yaml for one-click DigitalOcean App Platform deployment and a charts/nocodb Helm chart for Kubernetes, in addition to the Docker Compose examples under docker-compose/.
---
## 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, MySQL, SQLite, Redis): 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.