f1fbe0e29a
Archived 4 completed OpenSpec changes (2026-04-02): - phase-3-enterprise (100/100 tasks) — 6 Phase 3 capabilities synced - devops-documentation (48/48 tasks) — 3 new + 1 merged capability - bedroom-developer-docs (33/33 tasks) — 4 new capabilities synced - engineering-docs (superseded by 2026-03-29 archive) — no tasks Main spec library grows from 21 → 35 capabilities (+14 new): federation, multi-tenancy, oidc, soc2, w3c-dids, webhooks, database, operations, system-overview, api-reference, core-concepts, developer-guides, quick-start + deployment (merged additive requirements) Active changes: 0 — project board is clear for Phase 4 planning. 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