Headroom - Foundation

docs/headroom-executive-summary.md

@@ -0,0 +1,637 @@
+# HEADROOM
+## Resource Planning & Capacity Management System
+
+**Executive Summary & Technical Specification**
+
+---
+
+**Project Owner:** Santhosh J  
+**Date:** February 17, 2026  
+**Version:** 1.0  
+**Status:** Approved for Development  
+
+---
+
+## Table of Contents
+
+1. [Executive Overview](#executive-overview)
+2. [The Problem](#the-problem)
+3. [The Solution](#the-solution)
+4. [Technical Architecture](#technical-architecture)
+5. [Core Features](#core-features)
+6. [Quality Standards](#quality-standards)
+7. [Timeline & Phases](#timeline--phases)
+8. [Success Metrics](#success-metrics)
+
+---
+
+## Executive Overview
+
+### What is Headroom?
+
+Headroom is a web-based resource planning and capacity management tool designed to solve the allocation chaos faced by engineering managers juggling multiple projects and team members.
+
+**The Name:** "Headroom" captures the central question managers ask daily: "Do we have headroom for this new work?"
+
+### The Business Case
+
+**Current State:** Managing 10-15 developers across 10-12 concurrent projects using spreadsheets
+- Manual capacity calculations prone to errors
+- No validation mechanisms
+- Billing errors (over-allocation → overcharge, under-allocation → undercharge)
+- No visibility into team capacity
+- No audit trail
+
+**Future State:** Structured system that:
+- Automates capacity calculations
+- Validates allocations against estimates
+- Prevents billing errors before they happen
+- Provides clear visibility into team headroom
+- Tracks planned vs actual hours
+
+**ROI:** Manager time savings: 2+ hours → <30 minutes per monthly allocation cycle
+
+---
+
+## The Problem
+
+### Pain Points
+
+**1. Capacity Calculation Chaos**
+- Manual calculations across holidays, PTO, weekends
+- No systematic way to track who's available when
+- Hard to answer: "Who has capacity for new work?"
+
+**2. Billing Errors**
+- **Over-allocation:** More hours allocated than approved estimate → Overcharge client → Escalations
+- **Under-allocation:** Fewer hours allocated than approved estimate → Undercharge → Revenue loss
+- Both scenarios are unacceptable: "This money is my salary!"
+
+**3. No Validation**
+- Easy to over-allocate people or projects
+- No warnings when allocations exceed capacity
+- Spreadsheet formulas break, go unnoticed
+
+**4. Visibility Gap**
+- Can't easily see team utilization
+- Hard to compare planned vs actual hours
+- No forecasting capability
+
+**5. No Audit Trail**
+- Changes are invisible
+- Can't track who changed what allocation when
+
+---
+
+## The Solution
+
+### The Monthly Cycle
+
+Headroom organizes work around monthly capacity planning cycles:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  MONTHLY CYCLE                           │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  1. CAPACITY PLANNING                                    │
+│     • Define team members (name, role, rate)            │
+│     • Mark holidays, PTO, weekends                       │
+│     • Set daily availability (0, 0.5, 1.0)              │
+│     OUTPUT: Individual & team capacity, revenue potential│
+│                                                          │
+│  2. PROJECT SETUP                                        │
+│     • Track project status (lifecycle states)           │
+│     • Define approved estimate (billable hours)         │
+│     • Forecast effort across months                      │
+│     OUTPUT: Month-wise forecast, over/under indicators  │
+│                                                          │
+│  3. RESOURCE ALLOCATION                                  │
+│     • Allocate hours per person per project per month   │
+│     • Validate: allocation ≤ capacity, allocation = estimate│
+│     • Track "untracked" resources (external teams)      │
+│     OUTPUT: Clear allocation view, RED/YELLOW flags     │
+│                                                          │
+│  4. ACTUALS TRACKING                                     │
+│     • Team members log hours worked (monthly)           │
+│     • Calculate utilization (planned vs actual)         │
+│     OUTPUT: Running & overall utilization metrics       │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Four Personas
+
+| Persona | Primary Use Case |
+|---------|------------------|
+| **Superuser** | System setup, configuration, master data management |
+| **Manager** | Resource planning, allocation, team oversight, approve estimates |
+| **Developer** | View allocations, log hours, understand own workload |
+| **Top Brass** | Executive reports, forecasts, budget visibility (read-only) |
+
+### Key Validation Rules
+
+**Over/Under Allocation Detection:**
+- **GREEN:** Allocation = Approved estimate (100%)
+- **YELLOW:** Under-allocated (<100%) → Will undercharge
+- **RED:** Over-allocated (>100%) → Will overcharge
+
+**Both under and over are flagged.** The goal: Always allocate 100% of approved estimate.
+
+---
+
+## Technical Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    ARCHITECTURE                          │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  FRONTEND (SvelteKit - Port 5173)                       │
+│  • Tailwind CSS + DaisyUI (UI components)              │
+│  • Recharts (visualizations)                            │
+│  • TanStack Table (data grids)                          │
+│  • Superforms + Zod (form validation)                   │
+│  • Vitest (unit tests) + Playwright (E2E tests)        │
+│                                                          │
+│  BACKEND (Laravel API - Port 3000)                      │
+│  • Laravel 12 (latest, PHP 8.4)                         │
+│  • Laravel API Resources (consistent JSON)              │
+│  • JWT Authentication (tymon/jwt-auth)                  │
+│  • Laravel Scribe (SwaggerUI API docs)                  │
+│  • PHPUnit + Pest (testing)                             │
+│                                                          │
+│  DATA LAYER                                              │
+│  • PostgreSQL (latest) (primary database)               │
+│  • Redis (latest) (query + response caching)            │
+│                                                          │
+│  INFRASTRUCTURE                                          │
+│  • Docker Compose (4 containers)                        │
+│  • Nginx Proxy Manager (reverse proxy)                  │
+│  • Code-mounted volumes (hot reload)                    │
+│  • .env configuration (all environments)                │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Why These Choices?
+
+**SvelteKit:**
+- Modern, reactive framework
+- Great for data-heavy dashboards
+- Smaller bundle sizes
+- Chosen over Vue/React for learning/modernization
+
+**Laravel:**
+- Project owner has PHP background
+- Robust API development framework
+- Rich ecosystem (Scribe, Pest, Pint)
+- Excellent PostgreSQL support
+
+**PostgreSQL:**
+- Production-grade from day 1 (avoid SQLite migration)
+- JSON operators for flexible queries
+- Better for reporting queries
+
+**Redis:**
+- Caching from day 1 (avoid refactoring debt)
+- Query caching + response caching
+- Automatic cache invalidation
+
+**JWT Authentication:**
+- Token-based (suitable for SPA)
+- Future-ready (easier mobile support later)
+
+### Deployment Architecture
+
+**Local Development:**
+- 4 Docker containers (frontend, backend, postgres, redis)
+- Code-mounted volumes (hot reload, no rebuild)
+- Docker Compose orchestration
+
+**Production:**
+- Same containerized setup
+- Nginx Proxy Manager routes:
+  - `/` → SvelteKit
+  - `/api/*` → Laravel API
+
+---
+
+## Core Features
+
+### 1. Capacity Planning
+
+**Inputs:**
+- Team member: Name, role, hourly rate
+- Calendar: Holidays, weekends
+- PTO requests
+- Daily availability: 0 (unavailable), 0.5 (half day), 1.0 (full day)
+
+**Outputs:**
+- Individual capacity (person-days per month)
+- Team capacity (total available person-days)
+- Possible revenue (if fully utilized)
+
+**Key Insight:** Availability is per-person, per-day. "1.0" means 100% of a productive day (hours per day configurable).
+
+---
+
+### 2. Project Management
+
+**Project Lifecycle:**
+```
+NA/Support → Initial → Gathering Estimates → Estimate Pending Approval
+                ↓
+        Estimate Rework ←───────┘
+                ↓
+        Estimate Approved → Funded → Scheduled → In-Progress
+                ↓
+        Ready for Prod → Done
+                ↓
+        [Optional: On-Hold, Cancelled]
+```
+
+**Key Attributes:**
+- **Approved Estimate:** Total billable hours approved by client
+- **Forecasted Effort:** Month-by-month breakdown of those hours
+- **Type:** Project (billable) vs Support (ongoing ops)
+
+**Validation:**
+- Sum of forecasted effort must equal approved estimate (±5% tolerance)
+- Alerts when monthly team allocation exceeds team capacity
+
+---
+
+### 3. Resource Allocation
+
+**The Allocation Matrix:**
+
+For a given month, view all projects vs all team members:
+
+```
+┌──────────────────────────────────────────────────────┐
+│ Project    │ Dev A │ Dev B │ Dev C │ Untracked │ Total│
+├────────────┼───────┼───────┼───────┼───────────┼─────┤
+│ Project X  │  40h  │  20h  │   0   │    10h    │ 70h │
+│ Project Y  │  20h  │  40h  │  30h  │     0     │ 90h │
+│ Project Z  │   0   │  80h  │  60h  │     0     │140h │
+├────────────┼───────┼───────┼───────┼───────────┼─────┤
+│ Total      │  60h  │ 140h  │  90h  │    10h    │300h │
+│ Capacity   │ 160h  │ 160h  │ 120h  │     ∞     │440h │
+│ % Util     │  38%  │  88%  │  75%  │    N/A    │ 68% │
+└──────────────────────────────────────────────────────┘
+```
+
+**Features:**
+- Visual indicators: GREEN (100%), YELLOW (<100%), RED (>100%)
+- "Untracked" resource for external team time (not billed)
+- Inline editing
+- Sortable, filterable
+
+**Validation Rules:**
+- Cannot allocate negative hours
+- Cannot allocate more than person's capacity (warning)
+- Sum of project allocations should equal approved estimate (±5%)
+
+---
+
+### 4. Actuals & Utilization
+
+**Data Entry:**
+- Team members log hours worked per project per month
+- Manual entry (monthly aggregate, can update weekly incrementally)
+- No time-tracking tool integration (MVP)
+
+**Calculations:**
+- **Running Utilization:** (Allocated hours YTD) / (Capacity YTD) × 100%
+- **Overall Utilization:** (Allocated hours this month) / (Capacity this month) × 100%
+- **Variance:** Actual hours - Allocated hours
+
+**Display:**
+- Utilization % shown alongside capacity view
+- Color-coded (low, optimal, high utilization)
+
+---
+
+### 5. Reports & Analytics
+
+**Core Reports:**
+
+| Report | Purpose | Filters |
+|--------|---------|---------|
+| **Forecast Summary** | Multi-period view of allocations and revenue | Date range, team, project, status |
+| **Utilization Summary** | Team and individual utilization trends | Date range, team member, role |
+| **Cost Summary** | Revenue forecasts based on allocations × rates | Date range, project, client |
+| **Allocation Report** | Who's allocated to what, month-by-month | Month, team, project |
+| **Variance Report** | Planned vs Actual analysis | Date range, project, person |
+
+**All reports:**
+- Highly customizable filters
+- On-screen display (PDF/CSV export deferred to Phase 2)
+- Cached for performance (Redis)
+
+---
+
+### 6. Role-Based Access Control (RBAC)
+
+**Permission Matrix:**
+
+| Action | Superuser | Manager | Developer | Top Brass |
+|--------|-----------|---------|-----------|-----------|
+| View all projects | ✅ | ✅ (read-only for others') | ❌ (assigned only) | ✅ (read-only) |
+| Create/edit projects | ✅ | ✅ (own projects) | ❌ | ❌ |
+| Allocate resources | ✅ | ✅ (own team only) | ❌ | ❌ |
+| View allocations | ✅ | ✅ | ✅ (own only) | ✅ |
+| Log hours | ✅ | ✅ | ✅ | ❌ |
+| View reports | ✅ | ✅ | ❌ | ✅ |
+| Configure system | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Quality Standards
+
+### Testing Requirements
+
+**Every change must include:**
+1. **Unit tests** (backend: PHPUnit, frontend: Vitest)
+2. **E2E tests** (Playwright)
+3. **Regression tests** (full suite on each change)
+
+**Coverage Target:** >70% (enforced in `/opsx-verify`)
+
+**Test Loop (Phase 2):**
+- E2E/Integration failure → Create GitHub issue → Fix → Retest → Close issue
+- (MVP: Fix inline, no issue creation)
+
+---
+
+### Code Review Checklist
+
+Before merge:
+- ✅ **Style:** PSR-12 (PHP), Prettier (JS), ESLint (SvelteKit)
+- ✅ **Standards:** Laravel conventions, SvelteKit best practices
+- ✅ **Security:** Input validation, SQL injection prevention, XSS protection
+- ✅ **Tests:** All tests passing, coverage >70%
+- ✅ **API Docs:** Scribe auto-generated documentation up-to-date
+
+---
+
+### Commit Standards
+
+**Granular commits:** One fix = one commit
+
+**Format:**
+```
+[Type] Brief description (50 chars max)
+
+Detailed explanation (optional, 72 char wrap)
+
+Refs: openspec/changes/<change-name>
+```
+
+**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+---
+
+## Timeline & Phases
+
+### MVP (Phase 1) - 6-8 Weeks
+
+**Sprint 1: Project Setup (1 week)**
+- Docker Compose setup (4 containers)
+- Laravel + SvelteKit scaffolding
+- Database schema design
+- JWT authentication
+
+**Sprint 2: Capacity Planning (1.5 weeks)**
+- Team member CRUD
+- Holiday/PTO calendar
+- Availability tracking
+- Capacity calculations
+
+**Sprint 3: Project Management (1.5 weeks)**
+- Project CRUD
+- Status state machine
+- Approved estimate tracking
+- Forecasted effort
+
+**Sprint 4: Resource Allocation (2 weeks)**
+- Allocation matrix UI
+- Validation rules (over/under detection)
+- Visual indicators (GREEN/YELLOW/RED)
+- Untracked resource bucket
+
+**Sprint 5: Actuals & Reporting (2 weeks)**
+- Time logging interface
+- Utilization calculations
+- 5 core reports with filters
+- Redis caching implementation
+
+**Sprint 6: Testing & Polish (1 week)**
+- E2E test coverage (Playwright)
+- Code review
+- Bug fixes
+- API documentation (Scribe)
+
+---
+
+### Phase 2 - Enhancements (3-4 weeks)
+
+**Deferred Features:**
+- Notifications (WebSocket) - ~6 hours
+- PDF/CSV exports - ~4 hours
+- Background jobs (Laravel Queue) - ~2 hours
+- Audit logging - ~3 hours
+- Advanced caching (pre-calculated reports) - ~4 hours
+- Issue-driven test loop - ~8 hours
+- Bug fixes from production use
+
+---
+
+### Phase 3 - Scale & Optimize (TBD)
+
+**Future Enhancements:**
+- Multi-tenancy
+- Mobile optimization
+- AI-powered forecasting
+- Integration APIs (time-tracking, accounting)
+- Advanced resource-level over/under forecasting
+
+---
+
+## Success Metrics
+
+### MVP Success Criteria
+
+**Functional Completeness:**
+- ✅ Users can define team capacity (members, holidays, PTO, availability)
+- ✅ Users can create projects with approved estimates
+- ✅ Users can allocate resources to projects month-by-month
+- ✅ Users can log actual hours worked
+- ✅ System validates allocations (over/under warnings)
+- ✅ Users can view 5 core reports (forecast, utilization, cost, allocation, variance)
+- ✅ RBAC enforced (4 personas: Superuser, Manager, Dev, Top Brass)
+
+**Quality Metrics:**
+- ✅ All tests passing (unit + E2E)
+- ✅ Code coverage >70%
+- ✅ Zero linting errors
+- ✅ API documentation auto-generated (SwaggerUI)
+- ✅ Docker Compose setup working (local dev)
+
+**Usability Metrics (Post-Launch):**
+- **Manager time savings:** Complete monthly allocation in <30 minutes (vs 2+ hours in spreadsheet)
+- **Billing accuracy:** Zero billing errors in first 3 months (over/under caught before invoicing)
+- **Adoption:** 90% of team members log actuals weekly
+
+---
+
+## Data Model (Simplified)
+
+### Core Entities
+
+**Team Member**
+- Name, Role, Hourly Rate, Active status
+
+**Project**
+- Project Code, Title, Status, Type, Approved Estimate, Forecasted Effort
+
+**Allocation**
+- Project + Team Member + Month + Allocated Hours
+
+**Actual**
+- Project + Team Member + Month + Hours Logged
+
+**Supporting Entities:**
+- Roles, Project Statuses, Project Types, Holidays, PTO
+
+### Key Relationships
+
+```
+TEAM_MEMBER ──< ALLOCATION >── PROJECT
+      │                           │
+      └─< ACTUAL >────────────────┘
+      │
+      └─< PTO
+```
+
+---
+
+## Master Data / Taxonomy
+
+**Configurable Lists (Admin-managed):**
+
+**Roles/Teams:**
+- Frontend Developer
+- Backend Developer
+- QA Engineer
+- DevOps Engineer
+- UX Designer
+- Project Manager
+- Architect
+
+**Project Statuses:**
+- NA/Support, Initial, Gathering Estimates, Estimate Pending Approval, Estimate Rework, Estimate Approved, Funded, Scheduled, In-Progress, Ready for Prod, Done, On-Hold, Cancelled
+
+**Project Types:**
+- Project (billable)
+- Support (ongoing ops)
+
+**Availability Options:**
+- 0 (unavailable/PTO)
+- 0.5 (half day)
+- 1.0 (full day)
+
+---
+
+## Explicitly Out of Scope
+
+**Features NOT included:**
+- Time-tracking tool integration (manual entry only)
+- Mobile app (desktop web app only)
+- Invoicing integration (billing forecasts only, not actual invoicing)
+- Project task management (project-level tracking only, not task-level)
+- Calendar sync (Google, Outlook) - manual PTO/holiday entry
+- AI-powered forecasting (rule-based validation sufficient for MVP)
+
+---
+
+## Key Design Decisions
+
+### Decision Log Summary
+
+| Decision | Rationale |
+|----------|-----------|
+| **SvelteKit (separate from Laravel)** | Clean separation, modern framework, worth the learning curve |
+| **Redis caching from day 1** | Prevents refactoring debt ("No need to sweat on refactoring it everywhere") |
+| **JWT authentication** | Token-based, future-ready for mobile |
+| **PostgreSQL from day 1** | Avoid migration pain, production-grade |
+| **Defer notifications (WebSocket)** | Not time-critical for monthly planning, saves 6 hours |
+| **Defer PDF/CSV exports** | On-screen reports sufficient for MVP, adds 4 hours |
+| **>70% code coverage** | Fair but not too lenient, enforced from day 1 |
+| **Granular commits** | One fix = one commit, better git history |
+| **Both over and under-forecast flagged** | "This money is my salary!" - 100% allocation is goal |
+
+---
+
+## Project Philosophy
+
+### Guiding Principles
+
+1. **Quality over speed** - >70% test coverage, code review, security checks from day 1
+2. **Prevent technical debt** - Redis from day 1, containerization from start
+3. **100% allocation is the goal** - Both over and under-forecast are problems
+4. **Manager time is valuable** - Reduce monthly allocation time from 2+ hours to <30 minutes
+5. **Billing accuracy is critical** - Zero tolerance for over/under-charging clients
+6. **Defer, don't compromise** - Features deferred to Phase 2, not cut or half-implemented
+
+---
+
+## Contact & Ownership
+
+**Project Owner:** Santhosh J  
+**Project Type:** Magnum Opus ("This is my magnum opus project as of date.")  
+**Intended Users:** Self + Associate  
+**Timeline:** MVP in 6-8 weeks, Phase 2 in 3-4 weeks  
+
+---
+
+## Appendix: Technology Stack Summary
+
+### Backend
+- Laravel 12 (latest, PHP 8.4-FPM)
+- PostgreSQL (latest)
+- Redis (latest)
+- JWT Authentication (tymon/jwt-auth)
+- Laravel Scribe (SwaggerUI)
+- PHPUnit + Pest (testing)
+
+### Frontend
+- SvelteKit
+- Tailwind CSS + DaisyUI
+- Recharts (charts)
+- TanStack Table (data grids)
+- Superforms + Zod (forms & validation)
+- Vitest + Playwright (testing)
+
+### Infrastructure
+- Docker Compose (4 containers)
+- Nginx Proxy Manager (reverse proxy)
+- .env configuration
+- Code-mounted volumes (hot reload)
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** February 17, 2026  
+**Status:** Approved for Development  
+
+---
+
+*"Headroom - Know your capacity, prevent billing errors, deliver on time."*
+
+---
+
+**END OF EXECUTIVE SUMMARY**