d42c653eea
- engineering-docs → archive/2026-03-29-engineering-docs (63/63 tasks complete) - phase-2-production-ready → archive/2026-03-29-phase-2-production-ready (89/89 tasks complete) - openspec/specs/ synced with all Phase 1 + Phase 2 + engineering-docs capabilities (22 specs total) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.0 KiB
2.0 KiB
ADDED Requirements
Requirement: Codebase structure document
The system SHALL include a document (docs/engineering/04-codebase-structure.md) that provides an annotated map of every top-level directory and key file in the repository, explaining what lives where and why.
Scenario: Full directory tree annotated
- WHEN a new engineer reads 04-codebase-structure.md
- THEN they SHALL find an annotated directory tree covering:
src/,tests/,docs/,sdk/,sdk-python/,sdk-go/,sdk-java/,terraform/,dashboard/,migrations/,openspec/,scripts/
Scenario: src/ subdirectory roles explained
- WHEN a new engineer reads 04-codebase-structure.md
- THEN they SHALL understand the role of each
src/subdirectory:controllers/(HTTP layer),services/(business logic),repositories/(data access),middleware/(cross-cutting concerns),utils/(shared utilities),types/(TypeScript interfaces),routes/(Express router definitions)
Scenario: Where to add new code explained
- WHEN a new engineer needs to add a new feature
- THEN the document SHALL tell them exactly where each type of code belongs: new endpoint → controller + route; new business logic → service; new DB query → repository; new shared utility → utils/
Scenario: Key files identified and explained
- WHEN a new engineer reads 04-codebase-structure.md
- THEN they SHALL find explanations of:
src/app.ts(Express app setup),src/server.ts(entry point),src/types/index.ts(canonical type definitions),src/utils/errors.ts(error hierarchy),docker-compose.yml(local dev stack),tsconfig.json(TypeScript config)
Scenario: DRY principle mapped to structure
- WHEN a new engineer reads 04-codebase-structure.md
- THEN they SHALL understand how the directory structure enforces DRY: one location for types, one for crypto utilities, one for JWT utilities, one for validators — and why duplication across these is a blocking PR issue