Files
headroom/docs/headroom-executive-summary.md

638 lines
21 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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**