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