Headroom - Foundation

openspec/changes/headroom-foundation/proposal.md

@@ -0,0 +1,68 @@
+## 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
+
+<!-- No existing capabilities are being modified - this is a greenfield project -->
+
+## 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