santhoshj/headroom

Fork 0

Files

Santhosh Janardhanan 04022b7e0b Headroom - Foundation

2026-02-17 02:10:23 -05:00

21 KiB

Raw Permalink Blame History

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

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

21 KiB Raw Permalink Blame History Unescape Escape