gongxue-base/openspec/specs/monorepo-structure/spec.md

monorepo-structure Specification

Purpose

TBD - created by archiving change migrate-to-turborepo. Update Purpose after archive.

Requirements

Requirement: Monorepo directory structure

The project SHALL adopt the Turborepo-recommended directory structure with apps/ for applications and packages/ for shared libraries.

Scenario: Directory layout exists

• WHEN a developer clones the repository
• THEN the root directory contains apps/server/, apps/admin/, and packages/typescript-config/ as npm workspace packages

Scenario: Legacy paths removed

• WHEN the migration is complete
• THEN top-level backend/ (moved to apps/server/) and frontend/ (moved to apps/admin/) directories no longer exist

Requirement: npm workspaces configuration

The root package.json SHALL declare workspaces field listing all app and package directories, enabling unified dependency management via npm.

Scenario: Install from root

• WHEN npm install is run at the project root
• THEN dependencies for all workspaces are installed and hoisted to root node_modules/

Scenario: Workspace-scoped scripts

• WHEN npm run test --workspace=apps/server is executed
• THEN only the backend test suite runs

Requirement: Shared TypeScript configuration

The project SHALL provide shared TypeScript configuration presets via packages/typescript-config/, including base.json, nestjs.json, and react-vite.json.

Scenario: Server inherits NestJS preset

• WHEN apps/server/tsconfig.json is read
• THEN it extends @gongxue/typescript-config/nestjs.json

Scenario: Admin inherits React preset

• WHEN apps/admin/tsconfig.json is read
• THEN it extends @gongxue/typescript-config/react-vite.json

Requirement: Docker Compose path compatibility

The docker-compose.yml SHALL reference build contexts using the new apps/ paths, and all services MUST build and start successfully.

Scenario: Docker compose build succeeds

• WHEN docker compose build is executed
• THEN server and admin images build without errors

Scenario: Docker compose up succeeds

• WHEN docker compose up is executed
• THEN all services (MySQL, server, admin) start and respond to requests