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