Engineering Design Document
Companion to the Vespertene Shop Technical Specification. Defines HOW the system is built — architectural constraints, patterns, tooling contracts, testing strategy, observability, and architecture decision records. Read once before Sprint 1, reference during code reviews.
Document Hierarchy
| Document | Answers | Audience | Update frequency |
|---|---|---|---|
| Spec doc | What is being built | Everyone | Stable |
| This EDD | How it is built | Engineers | Per significant decision |
CLAUDE.md | Distilled rules for Claude Code | Claude Code | Per sprint |
SPRINTS.md | Current sprint checklist | Engineers | Weekly |
| ADR log | Why decisions were made | Engineers | Append-only |
Sections
- Architectural Constraints — CAP theorem position, consistency boundaries, scalability limits
- Dependency Injection & IoC — Awilix, service patterns, cross-module workflow rules
- Feature Flags — Env-based Phase 1, Flagsmith Phase 2+, guard placement
- Plugin Architecture — Invite, downloads, promo plugins + workflow hooks
- Node, nvm & Tooling — Version pinning, Claude Code plugin, pre-commit hooks
- Frontend Patterns & Storybook — Atomic design, Server vs Client components, state management
- Testing Strategy — Pyramid, Playwright journeys, Newman API contracts, download scenarios
- Observability — Health checks, monitoring stack by phase, structured logging, OTel
- ADRs — All 8 architecture decisions with context, decision, and consequences
- Environment & Secrets — Fly.io secrets, Vercel env vars, rotation schedule
- Code Review Checklist — Security, architecture, testing, observability gates