21 KiB
21 KiB
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
- Executive Overview
- The Problem
- The Solution
- Technical Architecture
- Core Features
- Quality Standards
- Timeline & Phases
- 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:
- Unit tests (backend: PHPUnit, frontend: Vitest)
- E2E tests (Playwright)
- 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
- Quality over speed - >70% test coverage, code review, security checks from day 1
- Prevent technical debt - Redis from day 1, containerization from start
- 100% allocation is the goal - Both over and under-forecast are problems
- Manager time is valuable - Reduce monthly allocation time from 2+ hours to <30 minutes
- Billing accuracy is critical - Zero tolerance for over/under-charging clients
- 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