headroom/openspec/changes/headroom-foundation/proposal.md

Why

Engineering managers juggling 10-15 developers across 10-12 concurrent projects currently use error-prone spreadsheets for capacity planning and resource allocation. This leads to billing errors (over/under-allocation), no visibility into team headroom, manual capacity calculations, and no audit trail. The business impact is severe: over-allocation causes client escalations, under-allocation loses revenue, and managers waste 2+ hours monthly on manual allocation work.

What Changes

• New web application: Full-stack resource planning and capacity management system
• Capacity planning module: Team member management, holiday/PTO tracking, availability calculations
• Project management module: Project lifecycle tracking, approved estimates, forecasted effort distribution
• Resource allocation module: Monthly allocation matrix with validation (over/under-allocation detection)
• Actuals tracking module: Time logging interface, utilization calculations (running & overall)
• Reporting module: 5 core reports (forecast, utilization, cost, allocation, variance) with customizable filters
• Authentication system: JWT-based auth with 4 user roles (Superuser, Manager, Developer, Top Brass)
• Containerized deployment: Docker Compose setup with Laravel API, SvelteKit frontend, PostgreSQL, Redis

Capabilities

New Capabilities

• team-member-management: CRUD operations for team members with role, hourly rate, and active status tracking
• capacity-planning: Calculate individual and team capacity based on availability, holidays, PTO, and working days
• project-lifecycle: Manage projects through state machine (Initial → Estimates → Approved → Funded → In-Progress → Done) with approved estimates and forecasted effort
• resource-allocation: Allocate hours per person per project per month with validation against capacity and approved estimates
• allocation-validation: Detect and flag over/under-allocation (RED for >100%, YELLOW for <100%, GREEN for 100%)
• actuals-tracking: Log hours worked per project per person per month (manual entry, monthly aggregate)
• utilization-calculations: Calculate running utilization (YTD) and overall utilization (monthly) as percentage of capacity
• forecast-reporting: Multi-period forecast reports showing allocations, revenue, and variance by project/team/person
• utilization-reporting: Team and individual utilization trends with customizable date range and filters
• cost-reporting: Revenue forecasts based on allocations multiplied by hourly rates, filterable by project/client/team
• allocation-reporting: Monthly allocation matrix view showing who's allocated to what with utilization percentages
• variance-reporting: Planned vs actual analysis showing over/under-delivery by project and person
• role-based-access: Enforce permissions for 4 personas (Superuser, Manager, Developer, Top Brass) with different read/write access
• master-data-management: Configure roles, project statuses, project types, and availability options
• authentication: JWT-based token authentication with login, logout, and token refresh

Modified Capabilities

Impact

New Systems:

• Laravel 12 (latest) API (backend container, port 3000)
• SvelteKit web app (frontend container, port 5173)
• PostgreSQL (latest) database (data container, port 5432)
• Redis (latest) cache (cache container, port 6379)
• Docker Compose orchestration
• Nginx Proxy Manager routing (/api/* → Laravel, /* → SvelteKit)

Dependencies:

• PHP 8.4 (latest) with Laravel 12 (latest) framework
• Node (latest) with SvelteKit (latest)
• Tailwind CSS + DaisyUI (UI components)
• Recharts (visualizations)
• TanStack Table (data grids)
• Superforms + Zod (form validation)
• Laravel Scribe (SwaggerUI API documentation)
• Testing: PHPUnit, Pest, Vitest, Playwright

External Integrations:

• None for MVP (manual data entry only)

Breaking Changes:

• None (new system)

Migration Path:

• Greenfield project - no data migration needed
• Users will transition from spreadsheets to web application