headroom/openspec/changes/headroom-foundation/design.md

Context

Headroom is a greenfield web application to replace manual spreadsheet-based capacity planning for engineering teams. The current spreadsheet approach is error-prone, lacks validation, provides no audit trail, and wastes manager time (2+ hours monthly on allocation work).

Current State:

• No existing system to migrate from
• Team uses spreadsheets for capacity planning and resource allocation
• No automation, no validation, no visibility into team headroom

Constraints:

• MVP must be production-ready with >70% test coverage
• Must run containerized (Docker Compose) from day 1
• Existing Nginx Proxy Manager in environment (no Caddy/Traefik)
• Must support 10-15 developers across 10-12 concurrent projects
• Monthly capacity planning cycle (not real-time)

Stakeholders:

• Engineering managers (primary users)
• Team members (log hours, view allocations)
• Top brass (view reports only)
• Superuser/admin (system configuration)

---

Goals / Non-Goals

Goals:

• Automate capacity calculations (holidays, PTO, availability)
• Validate allocations against capacity and approved estimates
• Prevent billing errors (over/under-allocation detection)
• Provide clear visibility into team headroom
• Track planned vs actual hours for utilization analysis
• Generate 5 core reports with customizable filters
• Reduce manager allocation time from 2+ hours to <30 minutes per month
• Enforce role-based access control (4 personas)
• Maintain >70% test coverage with comprehensive E2E tests

Non-Goals:

• Real-time notifications (deferred to Phase 2, polling is acceptable for MVP)
• PDF/CSV report exports (deferred to Phase 2, on-screen only for MVP)
• Time-tracking tool integration (manual entry only for MVP)
• Multi-tenancy (single-tenant MVP, add tenant_id later)
• Mobile app (desktop web only)
• AI-powered forecasting (rule-based validation sufficient)

---

Decisions

Decision 1: Two-Container Architecture (Laravel API + SvelteKit Frontend)

Choice: Separate Laravel API backend and SvelteKit frontend in different containers.

Rationale:

• Clean separation of concerns (API vs UI)
• Easier to scale independently in future
• SvelteKit is modern and great for dashboards, worth learning curve
• Laravel provides robust API development (owner has PHP background)

Alternatives Considered:

• Laravel + Blade templates: Rejected (less interactive UI, harder for dashboards)
• Laravel + Vue (Inertia): Rejected (owner preferred Svelte over Vue)
• SvelteKit full-stack: Rejected (owner has PHP background, prefer Laravel for API)

Implementation:

• Frontend: SvelteKit (port 5173), Tailwind CSS + DaisyUI, Recharts, TanStack Table
• Backend: Laravel 12 (latest) (port 3000), PostgreSQL (latest), Redis (latest)
• Communication: REST API with Laravel API Resources for consistent JSON
• Reverse proxy: Existing Nginx Proxy Manager routes /api/* → Laravel, /* → SvelteKit

---

Decision 2: PostgreSQL from Day 1

Choice: Use PostgreSQL in production and development (no SQLite).

Rationale:

• Avoid migration pain later (SQLite → PostgreSQL is error-prone)
• Production-grade features (JSON operators, full-text search, advanced indexing)
• Better for reporting queries (complex aggregations, window functions)
• Docker volume mount preserves portability

Alternatives Considered:

• SQLite for local dev, PostgreSQL for prod: Rejected (migration pain, feature parity issues)

Implementation:

• PostgreSQL (latest, Alpine container)
• Volume-mounted to ./data/postgres for backup/portability
• Migrations from day 1 (Laravel migrations)
• UUIDs for primary keys (prevents ID enumeration, easier distributed systems later)

---

Decision 3: Redis Caching from Day 1

Choice: Implement query and response caching with Redis from the start.

Rationale:

• Owner insisted: "No need to sweat on refactoring it everywhere"
• Prevents technical debt accumulation
• Expensive queries (capacity calculations, reports) benefit immediately
• Easy automatic cache invalidation with Laravel

Alternatives Considered:

• Defer caching to Phase 2: Rejected (owner's preference for avoiding future refactoring)

Implementation:

• Redis (latest, Alpine container)
• Cache keys pattern: allocations:month:{YYYY-MM}, reports:forecast:{from}:{to}:{hash}
• TTL: 1 hour (allocations), 15 min (reports), 24 hours (master data)
• Automatic invalidation on mutations (create/update/delete triggers cache flush)
• Laravel cache facade for consistency

---

Decision 4: JWT Authentication (Token-Based)

Choice: JWT tokens instead of session-based authentication.

Rationale:

• Stateless (better for API-first architecture)
• Suitable for SPA frontend
• Easier to add mobile app later (future-proofing)
• Industry standard for REST APIs

Alternatives Considered:

• Laravel sessions: Rejected (owner preferred JWT for future mobile support)

Implementation:

• tymon/jwt-auth package
• Access token: 60 minute TTL
• Refresh token: 7 day TTL (stored in Redis, one-time use with rotation)
• Token claims: user UUID, role, permissions array
• Refresh endpoint rotates tokens on each use

---

Decision 5: SvelteKit Frontend Stack

Choice: SvelteKit + Tailwind CSS + DaisyUI + Recharts + TanStack Table + Superforms + Zod

Rationale:

• DaisyUI: Fast development, opinionated but speeds up dashboard creation
• Recharts: Good balance of power and simplicity for charts
• TanStack Table: Industry standard for data grids, powerful filtering/sorting
• Superforms + Zod: Type-safe validation, seamless SvelteKit Form Actions integration

Alternatives Considered:

• Shadcn/ui: Rejected (DaisyUI faster for MVP)
• Chart.js: Rejected (Recharts more powerful)
• Custom table component: Rejected (TanStack is proven, owner unfamiliar but trusts recommendation)

Implementation:

• Svelte stores for minimal UI state only (filters, modals)
• Fetch API for HTTP (no Axios, native is sufficient)
• Vitest for unit tests, Playwright for E2E tests

---

Decision 6: Allocation Validation Strategy

Choice: Soft validation with visual indicators (GREEN/YELLOW/RED), not hard blocks.

Rationale:

• Managers sometimes need flexibility to over-allocate temporarily
• Hard blocks would frustrate workflow
• Visual warnings catch errors while allowing override
• "This money is my salary!" — both over and under-allocation must be flagged

Validation Rules:

• GREEN: Allocation = Approved estimate (100%, within ±5% tolerance)
• YELLOW: Under-allocation (<95% of approved estimate) — will undercharge
• RED: Over-allocation (>105% of approved estimate) — will overcharge
• Person capacity: YELLOW warning at >100%, RED alert at >120%

Implementation:

• API returns validation status with each allocation response
• Frontend displays color-coded indicators in allocation matrix
• Tooltip shows exact variance ("Over by 20 hours, will overcharge client")

---

Decision 7: Monthly Aggregate Actuals (Not Daily)

Choice: Track actual hours as monthly totals, allowing incremental weekly updates.

Rationale:

• Monthly planning cycle doesn't require daily granularity
• Simplifies data model and UI
• Team members can update weekly and system accumulates
• No time-tracking integration for MVP (manual entry)

Alternatives Considered:

• Daily time logging: Rejected (over-engineering for MVP, adds complexity)
• Weekly buckets: Rejected (monthly is sufficient given monthly planning cycle)

Implementation:

• Actuals table: project_id, team_member_id, month (YYYY-MM), hours_logged
• UI allows replacing or incrementing monthly total
• Utilization calculated as: (Actual hours / Capacity) × 100%

---

Decision 8: Defer Real-Time Notifications to Phase 2

Choice: No WebSocket notifications in MVP, users refresh to see changes.

Rationale:

• Allocations are planned monthly, not time-critical
• WebSocket setup adds 6 hours of dev time
• Polling every 30s is acceptable alternative but also deferred
• Focus MVP on core allocation/reporting functionality

Alternatives Considered:

• WebSocket + 1 notification PoC (6 hours): Rejected (not critical for monthly planning)
• Polling-based notifications (2 hours): Rejected (also deferred, users can refresh)

Implementation (Phase 2):

• Laravel Broadcasting with Redis adapter
• SvelteKit WebSocket client
• Events: AllocationCreated, AllocationUpdated, EstimateApproved

---

Decision 9: Database Schema Design

Choice: Normalized schema with master data tables, JSON for forecasted effort, UUIDs for primary keys.

Key Tables:

• team_members: id (UUID), name, role_id (FK), hourly_rate, active
• projects: id (UUID), code (unique), title, status_id (FK), type_id (FK), approved_estimate, forecasted_effort (JSON)
• allocations: id (UUID), project_id (FK), team_member_id (FK), month (YYYY-MM), allocated_hours
• actuals: id (UUID), project_id (FK), team_member_id (FK), month (YYYY-MM), hours_logged
• roles, project_statuses, project_types: Master data tables
• holidays, ptos: Calendar data

Design Rationale:

• UUIDs: Prevent ID enumeration attacks, easier distributed systems later
• Normalized master data: Roles/statuses/types in separate tables for dynamic configuration
• Month as string (YYYY-MM): Simplifies queries, index-friendly, human-readable
• JSON for forecasted effort: Flexible structure {"2026-02": 40, "2026-03": 60}, easy to extend
• Soft deletes for projects: deleted_at timestamp for audit trail
• Active flag for team members: Preserve historical allocations when person leaves

Indexes:

• allocations: composite index on (project_id, month), (team_member_id, month)
• actuals: composite index on (project_id, month), (team_member_id, month)
• team_members: index on (role_id, active)
• projects: index on (status_id, type_id), unique on (code)

---

Decision 10: API Design Pattern

Choice: REST API with Laravel API Resources for consistent JSON responses.

Rationale:

• REST is simpler than GraphQL for this use case
• Laravel API Resources provide consistent transformation layer
• Standard HTTP verbs (GET, POST, PUT, DELETE)
• Easy to document with Laravel Scribe (SwaggerUI)

Endpoint Structure:

/api/auth/login (POST)
/api/auth/logout (POST)
/api/auth/refresh (POST)

/api/team-members (GET, POST)
/api/team-members/:id (GET, PUT, DELETE)

/api/projects (GET, POST)
/api/projects/:id (GET, PUT, DELETE)

/api/allocations?month=YYYY-MM (GET, POST)
/api/allocations/bulk (POST)
/api/allocations/:id (PUT, DELETE)

/api/actuals?month=YYYY-MM (GET, POST)
/api/actuals/bulk (POST)
/api/actuals/:id (PUT)

/api/reports/forecast?from=YYYY-MM&to=YYYY-MM (GET)
/api/reports/utilization?month=YYYY-MM (GET)
/api/reports/cost?month=YYYY-MM (GET)
/api/reports/allocation?month=YYYY-MM (GET)
/api/reports/variance?month=YYYY-MM (GET)

/api/master-data/roles (GET)
/api/master-data/statuses (GET)
/api/master-data/types (GET)

Response Format (Laravel API Resources):

{
  "data": { /* resource */ },
  "meta": { /* pagination, counts */ },
  "links": { /* HATEOAS links */ }
}

Error Format:

{
  "message": "Validation failed",
  "errors": {
    "allocated_hours": ["Must be greater than 0"]
  }
}

---

Decision 11: Testing Strategy

Choice: >70% code coverage with unit + E2E + regression tests on every change.

Test Layers:

• Backend Unit (PHPUnit): Model methods, service classes, utilities
• Backend Feature (Pest): API endpoints, authentication, authorization
• Frontend Unit (Vitest): Svelte components, stores, utilities
• E2E (Playwright): Critical user flows (login → allocate → view reports)

Coverage Targets:

• Backend: >80% (easier to test server-side logic)
• Frontend: >70% (UI testing is harder)
• Overall: >70% (enforced in /opsx-verify)

Test Data Strategy:

• Database seeders for test data (Laravel seeders)
• Factories for model generation (Laravel factories)
• Test fixtures for E2E tests (Playwright fixtures)

Regression Test Approach (MVP):

• Run full test suite on every change
• E2E tests cover happy paths + critical error cases
• Phase 2: Issue-driven loop (E2E failure → create GitHub issue → fix → retest)

Implementation:

• Pre-commit hooks: Run linters + unit tests
• CI/CD: Run full suite (unit + E2E) before merge
• openspec verify command: Check coverage, run tests, lint

---

Risks / Trade-offs

Risk: SvelteKit Learning Curve

Impact: Owner and associate unfamiliar with Svelte, may slow initial development.

Mitigation:

• SvelteKit has excellent documentation
• Simpler than React/Vue (less boilerplate)
• TanStack Table is framework-agnostic (owner unfamiliar but AI will guide)
• Start with simple components, iterate

---

Risk: Two-Container Complexity

Impact: More moving parts than single monolith, deployment overhead.

Mitigation:

• Docker Compose handles orchestration
• Code-mounted volumes for hot reload (no rebuild needed)
• Owner comfortable with Docker
• Cleaner architecture worth the overhead

---

Risk: Over-Allocation Soft Validation

Impact: Managers could ignore RED flags and over-allocate anyway.

Mitigation:

• Visual warnings are prominent (RED color, tooltip with exact impact)
• Reports show over-allocation clearly
• Phase 2: Add email notifications when allocations exceed threshold
• Manager discipline assumed (this is their job)

---

Risk: Manual Time Entry Accuracy

Impact: Team members may forget to log hours or log inaccurately.

Mitigation:

• Utilization reports highlight under-logging (planned > actual consistently)
• Manager can follow up with team members showing low actuals
• Phase 2: Integrate with time-tracking tools (Jira, Harvest, Toggl)
• Incremental weekly updates reduce forgetting

---

Risk: Cache Invalidation Bugs

Impact: Stale data shown if cache invalidation logic fails.

Mitigation:

• Comprehensive test coverage for cache invalidation logic
• Redis TTL ensures eventual consistency (max 1 hour stale)
• Cache keys are scoped (project, month, person)
• Invalidation triggered on all mutations (create/update/delete)
• Manual cache flush available for admins

---

Risk: JWT Token Security

Impact: Stolen tokens could allow unauthorized access.

Mitigation:

• Refresh token rotation (one-time use)
• Short access token TTL (60 minutes)
• Refresh tokens stored in Redis (revocable)
• HTTPS enforced via Nginx Proxy Manager
• Logout invalidates refresh token
• Token includes user role for authorization checks

---

Trade-off: No Real-Time Notifications

Benefit: Saves 6 hours of dev time, keeps MVP scope tight.

Cost: Users must manually refresh to see allocation changes.

Justification: Allocations are monthly planning activity, not time-critical. Acceptable for MVP.

---

Trade-off: No PDF/CSV Exports

Benefit: Faster MVP, avoids report formatting complexity.

Cost: Users cannot export reports for offline viewing or stakeholder sharing.

Justification: On-screen reports are primary value, exports are nice-to-have for Phase 2.

---

Trade-off: Manual Time Entry

Benefit: Avoids vendor lock-in, no integration complexity.

Cost: Team members must manually enter hours monthly.

Justification: Monthly aggregate is low overhead (~5 minutes per person per month).

---

Migration Plan

Deployment Steps:

1. Initial Setup:

   • Run docker-compose up (creates 4 containers)
   • Laravel migrations create database schema
   • Database seeders populate master data (roles, statuses, types)
   • Create superuser account via Laravel seeder

2. Data Import (Optional):

   • If team has historical spreadsheet data, create import script
   • Import team members (name, role, hourly rate)
   • Import active projects (code, title, approved estimate)
   • Do NOT import historical allocations (start fresh)

3. User Onboarding:

   • Train managers on allocation workflow (1 hour session)
   • Demo: capacity planning → project setup → allocation → reports
   • Provide Quick Start guide (Markdown doc)

4. Go-Live:

   • Managers create February 2026 capacity plan (holidays, PTO, availability)
   • Managers allocate resources for February
   • Team members log February actuals mid-month (incremental updates)
   • Month-end: Review utilization reports, adjust March allocations

Rollback Strategy:

• MVP is greenfield (no data migration to revert)
• If critical bug discovered, roll back to previous container image
• Docker Compose down/up with previous image tag
• PostgreSQL data persisted in volume (safe across container restarts)
• Zero-downtime rollback: Blue/green deployment (Phase 2, not needed for MVP)

Monitoring (Phase 2):

• Application logs (Laravel log files)
• Database performance (PostgreSQL slow query log)
• Cache hit rate (Redis INFO stats)
• API response times (Laravel Telescope or custom middleware)

---

Open Questions

Question 1: Hourly Rate Visibility

Should developers see their own hourly rate, or only managers/top brass?

Options:

• A) Developers can see their own rate (transparency)
• B) Developers cannot see rates (only allocations)

Recommendation: A (transparency fosters trust, rate is not secret in most orgs)

Decision: To be finalized with owner before implementation.

---

Question 2: Hours Per Day Configuration

Is "1.0 availability = 8 hours" globally configured, or per-project?

Options:

• A) Global setting (e.g., 1.0 = 8 hours for everyone)
• B) Per-team member (some people work 6-hour days)
• C) Per-project (different billing rates for different project types)

Recommendation: A (global setting, simplest for MVP)

Decision: Owner mentioned "configurable per project" but likely meant per team. Clarify.

---

Question 3: PTO Approval Workflow

Is PTO auto-approved, or does it require manager approval?

Options:

• A) Auto-approved (capacity reduced immediately)
• B) Requires approval (pending state until manager approves)

Recommendation: B (manager approval, prevents abuse)

Decision: Owner likely expects approval workflow. Confirm.

---

Question 4: Support Projects in Revenue Forecast

Should "Support" type projects appear in revenue forecasts?

Options:

• A) Exclude from revenue (they're ongoing ops, not billable)
• B) Include in revenue (still billable internally)

Recommendation: Ask owner's preference (may vary by org)

Decision: To be confirmed during implementation.

---

Question 5: Allocation Tolerance Threshold

What's the tolerance for "within estimate" (GREEN indicator)?

Current assumption: ±5% (e.g., 100-hour project allocated 95-105 hours is GREEN)

Confirm: Is 5% the right threshold, or should it be configurable?

Decision: Start with 5%, make configurable in Phase 2 if needed.

---

End of Design Document

Next Steps:

1. Review open questions with owner
2. Finalize database schema (ERD diagram)
3. Create tasks.md (implementation checklist)
4. Begin Sprint 1: Docker Compose setup + database migrations