Specification Documents
Complete reference to all project documentation. Each document provides deep-dive details on its topic.
Where to start: Start with the BRD (
brd/BRD-v3.md) for business context, then read the relevant design doc for your current area of work. Domain specs provide the deepest detail on individual features.
Developer project files:
CLAUDE.md (Claude Code config) |
spec.md (backend business rules) |
fm-app-spec.md (FM Flutter app spec)
— drop into your project roots.
Business & Product Requirements
| Document | Path | What It Covers |
|---|---|---|
| Business Requirements | brd/BRD-v3.md |
Full MoSCoW prioritization (36 items), success metrics, KPIs, 62 documented issues |
| Product Requirements | prd/PRD-v3.md |
User stories, personas, UX requirements, analytics plan |
Architecture & Design
| Document | Path | What It Covers |
|---|---|---|
| System Architecture | design/ARCHITECTURE.md |
Architecture decisions, request flow, tech stack rationale |
| Database Schema | design/SCHEMA.md |
ERD, all 26 tables, constraints, enums, migration SQL |
| API Design | design/API.md |
JSON:API spec, all endpoints, error handling, pagination |
| Authentication | design/AUTH.md |
OTP flow, PIN, JWT, session strategy, rate limiting |
| File Structure | design/FILE-STRUCTURE.md |
Original project layout (adapt to your stack) |
| Frontend Design | design/FRONTEND.md |
Vue 3 + Inertia design (for context on web admin) |
| WhatsApp Integration | design/WHATSAPP.md |
WAHA setup, templates, fallback, webhooks |
| Testing Strategy | design/TESTING.md |
Test pyramid, coverage targets, test data factories |
| Deployment | design/DEPLOYMENT.md |
Docker Compose, VPS, backup/recovery |
| Migration Plan | design/MIGRATION.md |
v2→v3 data migration strategy, validation |
| AI-Ready Design | design/AI-READY.md |
Service interfaces designed for future AI feature integration |
Domain Specifications
| Document | Path | What It Covers |
|---|---|---|
| Booking Spec | prd/booking-spec.md |
Full booking lifecycle, state machine, holds, conflicts |
| Facility Spec | prd/facility-spec.md |
Fields, locations, cities, scheduling profiles |
| Payment Spec | prd/payments-spec.md |
Payment recording, refunds, VAT calculations |
| Notification Spec | prd/notifications-spec.md |
WhatsApp templates, delivery, incoming messages |
| Auth Spec | prd/auth-spec.md |
OTP flow, PIN management, session handling |
| Admin Spec | prd/admin-spec.md |
Admin dashboard, booking grid, analytics views |
| FM Tools Spec | prd/fm-tools-spec.md |
Field manager web + mobile specifications |
| Mobile API Spec | prd/mobile-api-spec.md |
REST API design for Flutter apps |
| AI-Ready Spec | prd/ai-ready-spec.md |
Service interfaces for future AI features |
| Captain Spec | prd/captain-spec.md |
Captain feature (deferred, schema-only) |
Audit & Analysis Reports
| Document | Path | What It Covers |
|---|---|---|
| Structure Map | audit/01-structure-map.md |
Current v2 codebase structure |
| Feature Inventory | audit/02-feature-inventory.md |
43 features catalogued with complexity ratings |
| Git Forensics | audit/03-git-forensics.md |
1,291 commits, 7 architectural pivots |
| Evolution Report | audit/04-evolution-report.md |
18 development milestones |
| Pain Points | audit/05-pain-points-registry.md |
35 pain points (7 Critical, 18 Major, 10 Minor) |
| Testing Gaps | audit/06-testing-gaps.md |
14% coverage, 19 features with zero tests |
| ER Diagram | audit/07-er-diagram.md |
Entity-relationship diagram for the database schema |
Data & Analytics
| Document | Path | What It Covers |
|---|---|---|
| User & Booking Analysis | data/01-user-booking-analysis.md |
2,667 bookings, user segmentation |
| Business Metrics | data/02-business-metrics.md |
Revenue analysis, customer concentration |
| Data Anomalies | data/03-data-anomalies.md |
58.3% missing prices, 34.8% stale statuses |
| User Journey Map | data/04-user-journey-map.md |
Booking funnel, customer acquisition |
PostHog Analytics
| Document | Path | What It Covers |
|---|---|---|
| Traffic Analysis | analytics/PH-01-traffic-analysis.md |
Traffic patterns, sources, device breakdown |
| Funnel Analysis | analytics/PH-02-funnel-analysis.md |
Conversion funnels, drop-off points |
| Feature Usage | analytics/PH-03-feature-usage.md |
Feature adoption and usage patterns |
| Tracking Blind Spots | analytics/PH-04-tracking-blind-spots.md |
Gaps in analytics coverage |
Synthesis
| Document | Path | What It Covers |
|---|---|---|
| Understanding Summary | synthesis/SYNTH-01-understanding-summary.md |
Integrated analysis (43 features, 62 issues, 14 Critical) |
| Business Questions | synthesis/SYNTH-02-business-questions.md |
45 targeted questions (24 must-answer) |
| Gate Checklist | synthesis/SYNTH-03-gate-checklist.md |
Phase completion criteria |
Recommended reading order for a new backend developer: 1) This brief (you're here), 2) BRD-v3.md, 3) SCHEMA.md, 4) API.md, 5) booking-spec.md, 6) AUTH.md. These 6 documents cover ~80% of what you need to start coding.