Directus

# MISSION: Scaffold "Directus" 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 **Directus**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Directus
- **What It Does**: Directus wraps any supported SQL database (Postgres, MySQL, MariaDB, SQL Server, Oracle, SQLite, CockroachDB) with auto-generated REST and GraphQL APIs and a Vue-based admin Studio, adding auth, field-level permissions, and a native MCP server for AI agents.
- **Domain & Category**: Headless CMS
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A Knex-based query layer and adapter packages for storage keep the same API and Studio working across many SQL vendors and object stores, while extension code runs inside an isolated-vm sandbox so third-party hooks cannot destabilize the main API process.
- **Live Website Reference**: https://directus.io
- **Source Repository**: https://github.com/directus/directus
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Vue, TypeScript, Node.js, Express, Knex.js, PostgreSQL, GraphQL, Redis, Docker
- **Primary Language(s)**: TypeScript, Vue
- **License of the reference repo**: NOASSERTION
- **Frontend**: Vue — Renders the admin Studio (the "app"); a single-page app built with the Composition API.; Vite — Dev server and production bundler for the app package (vite build / vite --host scripts).; Pinia — Client-side store for the Studio (auth, collections, fields, permissions state).; Vue Router — Client-side routing between Studio modules (Content, Users, Settings, Insights).
- **Backend & APIs**: Express — HTTP server for the @directus/api package; middleware and routes registered under api/src.; Knex.js — SQL query builder underlying the database abstraction; drivers configured for pg, mysql2, sqlite3, oracledb, mssql.; GraphQL — graphql-compose and graphql-ws expose an auto-generated GraphQL API and subscriptions alongside REST.; isolated-vm — Sandboxes user-authored extension code (hooks, endpoints, operations) away from the host process.
- **Data & persistence**: PostgreSQL — Primary supported database driver via the pg package; also the default in the local dev compose file.; MySQL / MariaDB / SQLite / MSSQL / Oracle / CockroachDB — Additional database vendors Directus wraps through Knex adapters, each spun up in the debug compose file.; Redis — ioredis client backs caching and pub/sub for schema-cache invalidation across instances.
- **Infrastructure & deploy**: Docker — Production image builds the monorepo with pnpm, deploys the directus package, and runs it under pm2.; Storage drivers (S3, GCS, Azure, Cloudinary, Supabase, local) — Pluggable asset storage backends, each its own workspace package.; pm2 — Process manager the production Docker image runs the built directus package under.
- **Tooling, testing & ops**: Native MCP server — Exposes Directus data and actions to MCP-compatible AI clients (Claude, Cursor) under the same permission model as human users.; AI SDK (@ai-sdk/*) — Powers the in-Studio AI Assistant for content creation, translation, and workflow actions.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/directus/directus @ 5cf557b)
1. **The database layer is Knex-based, not a heavier ORM**: api/package.json depends on knex plus driver packages (pg, mysql2, sqlite3, oracledb, mssql) rather than an ORM like Prisma or TypeORM, so Directus can introspect and wrap any of these SQL dialects with the same query-builder abstraction instead of generating a schema per vendor.
2. **Studio, API, and SDK are separate pnpm workspace packages that compose into one server**: app/ (Vue Studio), api/ (Express API), sdk/ (TypeScript client), and directus/ (the published CLI/meta-package that re-exports both) are independent packages under pnpm-workspace.yaml; directus/cli.js is what actually starts the combined server in production.
3. **Extensions execute inside an isolated-vm sandbox, not the main process**: api/package.json depends on isolated-vm so that user-authored hooks, endpoints, and operations (loaded from packages/extensions) run in a separate V8 isolate rather than directly in the API process, limiting the blast radius of third-party extension code.
4. **Storage and database backends are both adapter packages**: Six separate packages (packages/storage-driver-local, -s3, -gcs, -azure, -cloudinary, -supabase) implement the same storage interface, mirroring how Knex drivers abstract the database, so self-hosters choose object storage independently of which SQL vendor they run.
5. **The production Docker image defaults to SQLite, not Postgres**: The Dockerfile runtime stage sets ENV DB_CLIENT="sqlite3" and DB_FILENAME=/directus/database/database.sqlite as the out-of-the-box default, even though the local dev docker-compose.yml spins up Postgres, MySQL, MariaDB, MSSQL, Oracle, and CockroachDB for testing every adapter.
6. **AI and MCP access reuse the existing role-based permission system**: The README describes the native MCP server and AI Assistant as operating "under the same role-based permissions as human users," so AI access control is implemented as another consumer of the existing permissions engine rather than a parallel authorization path.
---
## 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 / MariaDB / SQLite / MSSQL / Oracle / CockroachDB, 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.