stack/docs/scratchpads/1-project-scaffold.md

Issue #1: Project scaffold (monorepo, NestJS, Next.js 16)

Objective

Set up the monorepo structure with pnpm workspaces + TurboRepo containing:

• apps/api (NestJS)
• apps/web (Next.js 16)
• packages/shared (types, utilities)
• packages/ui (shared components)
• packages/config (shared configuration)

Requirements

• pnpm workspace configuration
• TurboRepo for build orchestration
• TypeScript strict mode
• ESLint + Prettier
• Vitest for unit tests
• Initial package.json scripts

Approach

1. Initialize root package.json with pnpm workspaces
2. Configure TurboRepo (turbo.json)
3. Set up shared packages first (config, shared, ui)
4. Create NestJS API app
5. Create Next.js 16 web app
6. Configure TypeScript, ESLint, Prettier at root level
7. Set up Vitest for testing
8. Add build/dev/test scripts

Progress

• Initialize pnpm workspace configuration
• Set up TurboRepo for build orchestration
• Create packages/config
• Create packages/shared
• Create packages/ui
• Create apps/api (NestJS)
• Create apps/web (Next.js 16)
• Configure TypeScript strict mode
• Set up ESLint + Prettier
• Configure Vitest
• Add initial package.json scripts
• Test build and verify

Testing Results

• pnpm build - All 4 packages build successfully
• pnpm test - All 19 tests pass (shared: 10, api: 3, ui: 4, web: 2)

Structure Created

mosaic-stack/
├── apps/
│   ├── api/              # NestJS 11.1.12 API
│   │   ├── src/
│   │   │   ├── main.ts
│   │   │   ├── app.module.ts
│   │   │   ├── app.controller.ts
│   │   │   └── app.service.ts
│   │   └── package.json
│   └── web/              # Next.js 16.1.6 with App Router
│       ├── src/app/
│       │   ├── layout.tsx
│       │   ├── page.tsx
│       │   └── globals.css
│       └── package.json
├── packages/
│   ├── config/           # Shared TypeScript, ESLint, Prettier configs
│   │   ├── typescript/
│   │   ├── eslint/
│   │   └── prettier/
│   ├── shared/           # Shared types and utilities
│   │   └── src/
│   │       ├── types/
│   │       └── utils/
│   └── ui/               # Shared React components
│       └── src/
│           └── components/
├── package.json          # Root package.json with scripts
├── pnpm-workspace.yaml   # Workspace configuration
├── turbo.json            # TurboRepo configuration
├── tsconfig.json         # Root TypeScript config
├── eslint.config.js      # Root ESLint config
└── .prettierrc.js        # Root Prettier config

Key Scripts

• pnpm dev - Start all dev servers (API: 3001, Web: 3000)
• pnpm build - Build all packages
• pnpm test - Run all tests
• pnpm lint - Run linting
• pnpm format - Format all files

Notes

• Version: 0.0.1 (M1-Foundation milestone)
• Using pnpm 10.19.0 for package management
• TurboRepo 2.8.0 for efficient build caching
• Next.js 16.1.6 with Turbopack for dev
• NestJS 11.1.12 with Vitest for testing
• TypeScript 5.8.2 in strict mode