Next.js

# MISSION: Scaffold "Next.js" 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 **Next.js**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Next.js
- **What It Does**: Next.js is the React framework maintained by Vercel, developed as a TypeScript and Rust monorepo where a native Rust workspace implements the Turbopack bundler and SWC-based compiler alongside the existing Webpack and Rspack build paths.
- **Domain & Category**: Fullstack React Framework
- **Production Scale**: 1M+ MAU
- **Development Mode**: HYBRID
- **Architectural Rationale**: Performance-critical compilation and bundling are implemented as Rust crates (Turbopack, SWC transforms) compiled to native addons, while the framework surface stays in TypeScript, letting Next.js run its full test matrix across three interchangeable bundlers without forking the codebase.
- **Live Website Reference**: https://nextjs.org
- **Source Repository**: https://github.com/vercel/next.js
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, JavaScript, React, Node.js, Rust, Webpack, Rspack, Jest, Vercel, Turborepo
- **Primary Language(s)**: JavaScript, TypeScript, Rust
- **License of the reference repo**: MIT
- **Frontend**: React — The framework Next.js extends; app-router and pages-router features build on React APIs.
- **Backend & APIs**: TypeScript — Implements the next package CLI, server runtime, and most of the framework surface.; Node.js — Runtime for the next CLI and server; the pinned version is tracked in .node-version.; Rust — Implements Turbopack and SWC-based transforms as native crates compiled via napi bindings.
- **Infrastructure & deploy**: Turborepo — Runs generator-based scripts (turbo gen error, turbo gen test) though the monorepo build itself is orchestrated by Lerna.; Vercel — Publishes the repository as a Vercel-made project; GitHub app settings for CI are checked into vercel.json.; Webpack — Default bundler for next build and next dev, alongside the Turbopack and Rspack alternatives.; Rspack — Alternate Rust-based bundler exercised by dedicated build/dev/test scripts and CI workflows.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/vercel/next.js @ d5b615e)
1. **Turbopack and SWC are implemented as Rust crates, not JS**: Cargo.toml defines a Rust workspace including crates/next-core, crates/next-custom-transforms, crates/next-napi-bindings, and the turbopack/crates/* family, compiled to native Node addons; this is why Rust is the third-largest language in the repository by bytes.
2. **Three bundlers are supported and tested side by side**: The root package.json defines test-*-webpack, test-*-turbo, and test-*-rspack script variants (test-dev-webpack, test-dev-turbo, test-dev-rspack, etc.), and rspack/package.json and rspack-nextjs-build-integration-tests.yml show Rspack is exercised as a distinct bundler option alongside Webpack and Turbopack.
3. **Monorepo tooling mixes Lerna, Turborepo generators, and pnpm workspaces**: lerna.json and the clean script (lerna clean -y && lerna run clean) drive package-level operations, while turbo.json defines cacheable build/dev tasks and package.json also exposes turbo gen error and turbo gen test generators; pnpm-workspace.yaml lists packages/* as the workspace root.
4. **create-next-app is a standalone, minimally-dependent CLI package**: packages/create-next-app/package.json bundles its CLI with @vercel/ncc into a single dist/index.js, keeping its dependency surface (commander, prompts, cross-spawn, tar) separate from the main next package so project scaffolding stays fast to install.
5. **The test suite runs against every bundler and every rendering mode**: Root package.json scripts combine mode (test-dev, test-start, test-deploy) with bundler (webpack, turbo, rspack) to produce a matrix like test-dev-turbo and test-deploy-webpack, run through scripts/run-jest.sh against the Jest-based integration suite in test/.
6. **create-next-app and font packages ship as separate npm publishes**: packages/create-next-app, packages/font, and packages/eslint-config-next each have their own package.json and are published independently of the main next package, letting scaffolding, font optimization, and lint config version separately.
---
## 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: 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.