# 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/ ``` **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**