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

1. Project Setup & Infrastructure

• 1.1 Create Docker Compose configuration (frontend, backend, postgres, redis containers)
• 1.2 Configure Dockerfile for Laravel backend (PHP 8.4-FPM, use :latest tag)
• 1.3 Configure Dockerfile for SvelteKit frontend (Node:latest)
• 1.4 Set up volume mounts for code (hot reload) and data (PostgreSQL, Redis)
• 1.5 Configure environment variables (.env files for frontend and backend)
• 1.6 Test Docker Compose startup (all 4 containers running)
• 1.7 Configure Nginx Proxy Manager routes (/api/* → Laravel, /* → SvelteKit)

2. Backend Foundation (Laravel)

• 2.1 Initialize Laravel 12 (latest) project with required dependencies
• 2.2 Install tymon/jwt-auth, predis/predis, knuckleswtf/scribe
• 2.3 Install pestphp/pest, laravel/pint for testing and linting
• 2.4 Configure PostgreSQL connection in config/database.php
• 2.5 Configure Redis connection for cache and sessions
• 2.6 Set up JWT authentication configuration (60min access, 7day refresh)
• 2.7 Configure CORS for SvelteKit frontend origin
• 2.8 Create API route structure (api.php)

3. Frontend Foundation (SvelteKit)

• 3.1 Initialize SvelteKit project with TypeScript
• 3.2 Install Tailwind CSS and DaisyUI
• 3.3 Install Recharts, TanStack Table (@tanstack/svelte-table)
• 3.4 Install Superforms (sveltekit-superforms) and Zod
• 3.5 Install Vitest and Playwright for testing
• 3.6 Configure Tailwind with DaisyUI theme
• 3.7 Create API client service (fetch wrapper with JWT token handling)
• 3.8 Create auth store (Svelte store for user, token management)
• 3.9 Create layout components (+layout.svelte, navigation)

4. Database Schema & Migrations

• 4.1 Create migration: roles table (id, name, description)
• 4.2 Create migration: project_statuses table (id, name, order, is_active, is_billable)
• 4.3 Create migration: project_types table (id, name, description)
• 4.4 Create migration: team_members table (id UUID, name, role_id, hourly_rate, active)
• 4.5 Create migration: projects table (id UUID, code unique, title, status_id, type_id, approved_estimate, forecasted_effort JSON)
• 4.6 Create migration: allocations table (id UUID, project_id, team_member_id, month, allocated_hours)
• 4.7 Create migration: actuals table (id UUID, project_id, team_member_id, month, hours_logged)
• 4.8 Create migration: holidays table (id UUID, date, name, description)
• 4.9 Create migration: ptos table (id UUID, team_member_id, start_date, end_date, reason, status)
• 4.10 Create migration: users table (id UUID, name, email, password, role enum)
• 4.11 Add indexes (composite on allocations/actuals for project+month, member+month)
• 4.12 Run migrations and verify schema

5. Database Seeders

• 5.1 Create seeder: roles (Frontend Dev, Backend Dev, QA, DevOps, UX, PM, Architect)
• 5.2 Create seeder: project_statuses (13 statuses with correct order)
• 5.3 Create seeder: project_types (Project, Support)
• 5.4 Create seeder: users (create superuser account for testing)
• 5.5 Run seeders and verify master data populated

6. Laravel Models & Relationships

• 6.1 Create TeamMember model with role relationship
• 6.2 Create Project model with status, type relationships, casts for forecasted_effort JSON
• 6.3 Create Allocation model with project, team_member relationships
• 6.4 Create Actual model with project, team_member relationships
• 6.5 Create Role, ProjectStatus, ProjectType models
• 6.6 Create Holiday, PTO models
• 6.7 Create User model with JWT authentication traits
• 6.8 Define model factories for testing (TeamMemberFactory, ProjectFactory, etc.)

7. Authentication (Backend)

• 7.1 Create AuthController (login, logout, refresh methods)
• 7.2 Implement login endpoint (validate credentials, generate JWT tokens)
• 7.3 Implement logout endpoint (invalidate refresh token in Redis)
• 7.4 Implement refresh endpoint (validate refresh token, rotate tokens)
• 7.5 Create JWT middleware for protecting routes
• 7.6 Store refresh tokens in Redis with 7-day TTL
• 7.7 Write unit tests for AuthController
• 7.8 Write feature tests for auth endpoints

8. Authentication (Frontend)

• 8.1 Create login page (/login route)
• 8.2 Create login form with Superforms + Zod validation
• 8.3 Implement auth API client methods (login, logout, refresh)
• 8.4 Create auth store (persist tokens in localStorage)
• 8.5 Implement token refresh logic (interceptor for 401 responses)
• 8.6 Create auth guard for protected routes (hooks.server.ts)
• 8.7 Add logout functionality to navigation
• 8.8 Write E2E test for login flow (Playwright)

9. Team Member Management (Backend)

• 9.1 Create TeamMemberController (index, store, show, update, destroy)
• 9.2 Create TeamMemberRequest for validation (name required, hourly_rate > 0)
• 9.3 Create TeamMemberResource for JSON transformation
• 9.4 Create TeamMemberPolicy for authorization (managers can CRUD)
• 9.5 Implement soft delete prevention (cannot delete if allocations exist)
• 9.6 Add API routes for team members
• 9.7 Write unit tests for TeamMember model
• 9.8 Write feature tests for team member endpoints

10. Team Member Management (Frontend)

• 10.1 Create team members list page (/team-members route)
• 10.2 Create team member create/edit form with Superforms + Zod
• 10.3 Implement team member API client methods (CRUD)
• 10.4 Display team members in TanStack Table (sortable, filterable)
• 10.5 Add active/inactive toggle UI
• 10.6 Add hourly rate display (formatted as currency)
• 10.7 Implement delete with confirmation modal
• 10.8 Write unit tests for team member components (Vitest)
• 10.9 Write E2E test for team member CRUD (Playwright)

11. Project Management (Backend)

• 11.1 Create ProjectController (index, store, show, update, destroy)
• 11.2 Create ProjectRequest for validation (code unique, approved_estimate > 0 if status >= Approved)
• 11.3 Create ProjectResource for JSON transformation
• 11.4 Create ProjectPolicy for authorization (managers can edit own projects)
• 11.5 Implement project status state machine validation
• 11.6 Implement forecasted effort validation (sum must equal approved estimate ±5%)
• 11.7 Add API routes for projects
• 11.8 Write unit tests for Project model and status transitions
• 11.9 Write feature tests for project endpoints

12. Project Management (Frontend)

• 12.1 Create projects list page (/projects route)
• 12.2 Create project create/edit form with Superforms + Zod
• 12.3 Implement project API client methods (CRUD)
• 12.4 Display projects in TanStack Table (sortable, filterable by status/type)
• 12.5 Add status dropdown (reflect state machine transitions)
• 12.6 Add forecasted effort input (JSON editor or month-by-month fields)
• 12.7 Display validation warnings (forecasted effort ≠ approved estimate)
• 12.8 Write unit tests for project components (Vitest)
• 12.9 Write E2E test for project creation and status transitions (Playwright)

13. Capacity Planning (Backend)

• 13.1 Create HolidayController (index, store, destroy)
• 13.2 Create PTOController (index, store, update, destroy with approval workflow)
• 13.3 Create CapacityService for capacity calculations
• 13.4 Implement calculateIndividualCapacity method (working days × availability - PTO - holidays)
• 13.5 Implement calculateTeamCapacity method (sum of individual capacities for active members)
• 13.6 Implement calculatePossibleRevenue method (capacity × hourly rates)
• 13.7 Add API routes for capacity endpoint (/api/capacity?month=YYYY-MM)
• 13.8 Implement Redis caching for capacity calculations (1 hour TTL)
• 13.9 Write unit tests for CapacityService
• 13.10 Write feature tests for capacity endpoints

14. Capacity Planning (Frontend)

• 14.1 Create capacity planning page (/capacity route)
• 14.2 Create calendar component for displaying month grid
• 14.3 Implement availability editor (click day to set 0, 0.5, 1.0)
• 14.4 Display holidays (H marker on dates)
• 14.5 Display weekends (O marker on dates)
• 14.6 Create PTO request form
• 14.7 Display individual and team capacity summary
• 14.8 Display possible revenue calculation
• 14.9 Write unit tests for capacity components (Vitest)
• 14.10 Write E2E test for capacity planning workflow (Playwright)

15. Resource Allocation (Backend)

• 15.1 Create AllocationController (index, store, update, destroy, bulk methods)
• 15.2 Create AllocationRequest for validation (hours >= 0, month format YYYY-MM)
• 15.3 Create AllocationResource for JSON transformation
• 15.4 Create AllocationPolicy for authorization (managers can allocate own team members)
• 15.5 Implement allocation validation service (check capacity, approved estimate)
• 15.6 Implement bulk allocation endpoint (create/update multiple allocations)
• 15.7 Add API routes for allocations (/api/allocations?month=YYYY-MM)
• 15.8 Implement Redis cache invalidation on allocation mutations
• 15.9 Write unit tests for allocation validation logic
• 15.10 Write feature tests for allocation endpoints

16. Resource Allocation (Frontend)

• 16.1 Create allocation matrix page (/allocations route)
• 16.2 Create allocation matrix component using TanStack Table
• 16.3 Implement inline editing for allocation hours
• 16.4 Display projects as rows, team members as columns
• 16.5 Display row totals (total hours per project)
• 16.6 Display column totals (total hours per team member)
• 16.7 Display utilization percentages per team member
• 16.8 Implement color-coded indicators (GREEN/YELLOW/RED for over/under allocation)
• 16.9 Add "Untracked" resource column
• 16.10 Implement month selector (navigate between months)
• 16.11 Add bulk allocation actions (copy previous month, clear all)
• 16.12 Write unit tests for allocation matrix logic (Vitest)
• 16.13 Write E2E test for allocation workflow (Playwright)

17. Actuals Tracking (Backend)

• 17.1 Create ActualController (index, store, update, bulk methods)
• 17.2 Create ActualRequest for validation (hours >= 0, cannot log future months)
• 17.3 Create ActualResource for JSON transformation
• 17.4 Create ActualPolicy for authorization (developers can log own hours only)
• 17.5 Implement validation: cannot log to completed/cancelled projects (configurable)
• 17.6 Implement bulk actuals endpoint
• 17.7 Add API routes for actuals (/api/actuals?month=YYYY-MM)
• 17.8 Implement Redis cache invalidation on actuals mutations
• 17.9 Write unit tests for actuals validation
• 17.10 Write feature tests for actuals endpoints

18. Actuals Tracking (Frontend)

• 18.1 Create actuals entry page (/actuals route)
• 18.2 Create actuals matrix component (similar to allocations matrix)
• 18.3 Display allocated hours vs actual hours side by side
• 18.4 Highlight variances (over/under delivery)
• 18.5 Allow developers to see only their own actuals (RBAC check)
• 18.6 Implement bulk update for multiple projects
• 18.7 Write unit tests for actuals components (Vitest)
• 18.8 Write E2E test for actuals logging (Playwright)

19. Utilization Calculations (Backend)

• 19.1 Create UtilizationService for utilization calculations
• 19.2 Implement calculateRunningUtilization method (YTD allocated / YTD capacity)
• 19.3 Implement calculateOverallUtilization method (monthly allocated / monthly capacity)
• 19.4 Implement calculateActualUtilization method (monthly actuals / monthly capacity)
• 19.5 Implement team-level utilization aggregation
• 19.6 Add utilization data to allocation and actuals responses
• 19.7 Write unit tests for UtilizationService
• 19.8 Write feature tests for utilization calculations

20. Reporting - Forecast (Backend)

• 20.1 Create ReportController with forecast method
• 20.2 Implement forecast report query (multi-period allocations)
• 20.3 Calculate revenue forecast (allocations × hourly rates)
• 20.4 Display variance indicators (forecasted vs approved estimate)
• 20.5 Implement filters (project, status, type, team, date range)
• 20.6 Create ForecastReportResource for JSON transformation
• 20.7 Add API route /api/reports/forecast
• 20.8 Implement Redis caching for forecast reports (15 min TTL)
• 20.9 Write unit tests for forecast report logic
• 20.10 Write feature tests for forecast endpoint

21. Reporting - Forecast (Frontend)

• 21.1 Create forecast report page (/reports/forecast route)
• 21.2 Create forecast report table component
• 21.3 Display multi-period view (month columns)
• 21.4 Display variance indicators (GREEN/YELLOW/RED)
• 21.5 Implement date range selector
• 21.6 Implement filters (project, status, type, team)
• 21.7 Display summary aggregations (total approved, total allocated, variance)
• 21.8 Add revenue forecast chart (Recharts line chart)
• 21.9 Write E2E test for forecast report (Playwright)

22. Reporting - Utilization (Backend)

• 22.1 Add utilization method to ReportController
• 22.2 Implement utilization report query (team and individual trends)
• 22.3 Calculate planned vs actual utilization
• 22.4 Implement filters (team member, role, date range)
• 22.5 Create UtilizationReportResource for JSON transformation
• 22.6 Add API route /api/reports/utilization
• 22.7 Implement Redis caching for utilization reports
• 22.8 Write feature tests for utilization endpoint

23. Reporting - Utilization (Frontend)

• 23.1 Create utilization report page (/reports/utilization route)
• 23.2 Display team-level utilization summary
• 23.3 Display individual utilization breakdown
• 23.4 Add utilization trend chart (Recharts line chart)
• 23.5 Color-code utilization bands (< 70% blue, 80-100% green, > 100% yellow/red)
• 23.6 Implement filters (team member, role, date range)
• 23.7 Display utilization distribution chart (how many in each band)
• 23.8 Write E2E test for utilization report (Playwright)

24. Reporting - Cost (Backend)

• 24.1 Add cost method to ReportController
• 24.2 Implement cost report query (allocations × hourly rates)
• 24.3 Calculate possible revenue (full capacity utilization)
• 24.4 Calculate forecasted revenue (current allocations)
• 24.5 Calculate revenue gap (possible - forecasted)
• 24.6 Implement filters (project, client, type, team, date range)
• 24.7 Create CostReportResource for JSON transformation
• 24.8 Add API route /api/reports/cost
• 24.9 Implement Redis caching for cost reports
• 24.10 Write feature tests for cost endpoint

25. Reporting - Cost (Frontend)

• 25.1 Create cost report page (/reports/cost route)
• 25.2 Display monthly revenue forecast
• 25.3 Display cost breakdown by project
• 25.4 Display possible revenue vs forecasted revenue
• 25.5 Display revenue gap analysis
• 25.6 Implement filters (project, type, team, date range)
• 25.7 Add revenue chart (Recharts bar chart)
• 25.8 Write E2E test for cost report (Playwright)

26. Reporting - Allocation (Backend)

• 26.1 Add allocation method to ReportController
• 26.2 Implement allocation report query (monthly matrix view)
• 26.3 Include utilization percentages
• 26.4 Implement filters (team, role, project, status)
• 26.5 Create AllocationReportResource for JSON transformation
• 26.6 Add API route /api/reports/allocation
• 26.7 Implement Redis caching for allocation reports
• 26.8 Write feature tests for allocation endpoint

27. Reporting - Allocation (Frontend)

• 27.1 Create allocation report page (/reports/allocation route)
• 27.2 Display allocation matrix with totals
• 27.3 Display utilization percentages
• 27.4 Highlight recent allocation changes (NEW/UPDATED badges)
• 27.5 Implement multi-month view option
• 27.6 Implement filters (team, role, project, status)
• 27.7 Write E2E test for allocation report (Playwright)

28. Reporting - Variance (Backend)

• 28.1 Add variance method to ReportController
• 28.2 Implement variance report query (planned vs actual comparison)
• 28.3 Calculate variance (actual - planned) and percentage
• 28.4 Flag over-delivery and under-delivery patterns
• 28.5 Implement filters (project, team, person, date range)
• 28.6 Create VarianceReportResource for JSON transformation
• 28.7 Add API route /api/reports/variance
• 28.8 Implement Redis caching for variance reports
• 28.9 Write feature tests for variance endpoint

29. Reporting - Variance (Frontend)

• 29.1 Create variance report page (/reports/variance route)
• 29.2 Display variance table (planned, actual, variance, variance %)
• 29.3 Color-code variances (positive green, negative red)
• 29.4 Display project-level variance aggregations
• 29.5 Display person-level variance aggregations
• 29.6 Add variance trend chart (Recharts)
• 29.7 Implement filters (project, team, person, date range)
• 29.8 Write E2E test for variance report (Playwright)

30. Role-Based Access Control (Backend)

• 30.1 Create role middleware for route protection
• 30.2 Implement permission checks in controllers
• 30.3 Create policies for all models (TeamMember, Project, Allocation, Actual)
• 30.4 Implement Superuser full access (bypass all checks)
• 30.5 Implement Manager permissions (own projects, own team allocations)
• 30.6 Implement Developer permissions (own allocations, own actuals)
• 30.7 Implement Top Brass permissions (read-only all reports)
• 30.8 Write unit tests for policies
• 30.9 Write feature tests for authorization (401, 403 responses)

31. Role-Based Access Control (Frontend)

• 31.1 Add role to auth store
• 31.2 Implement route guards based on role (hooks.server.ts)
• 31.3 Hide UI elements based on permissions (v-if directives)
• 31.4 Show read-only state for Top Brass users
• 31.5 Filter visible projects for Managers (own projects editable, others read-only)
• 31.6 Filter visible data for Developers (only assigned projects)
• 31.7 Write E2E tests for RBAC (different user roles)

32. Master Data Management (Backend)

• 32.1 Create MasterDataController (roles, statuses, types endpoints)
• 32.2 Create RoleController for managing roles (Superuser only)
• 32.3 Create ProjectStatusController for managing statuses (Superuser only)
• 32.4 Create ProjectTypeController for managing types (Superuser only)
• 32.5 Implement validation: cannot delete role/status/type in use
• 32.6 Add API routes for master data endpoints
• 32.7 Implement Redis caching for master data (24 hour TTL)
• 32.8 Write feature tests for master data endpoints

33. Master Data Management (Frontend)

• 33.1 Create master data management page (/admin/master-data route, Superuser only)
• 33.2 Display roles list with CRUD actions
• 33.3 Display project statuses list with reordering and CRUD actions
• 33.4 Display project types list with CRUD actions
• 33.5 Implement master data forms (create/edit)
• 33.6 Write E2E test for master data management (Playwright)

34. API Documentation (Backend)

• 34.1 Add Scribe annotations to all controllers (@group, @response tags)
• 34.2 Configure Scribe (scribe.php config file)
• 34.3 Generate API documentation (php artisan scribe:generate)
• 34.4 Verify SwaggerUI accessible at /api/documentation
• 34.5 Add example requests and responses to documentation
• 34.6 Add authentication section to API docs

35. Testing & Code Quality

• 35.1 Write comprehensive unit tests (backend models, services, utilities)
• 35.2 Write feature tests for all API endpoints (Laravel Pest)
• 35.3 Write unit tests for frontend components (Vitest)
• 35.4 Write E2E tests for critical flows (Playwright: login, allocate, report)
• 35.5 Configure pre-commit hooks (Laravel Pint, ESLint, Prettier)
• 35.6 Run PHPStan static analysis (level 5+)
• 35.7 Generate code coverage report (verify >70%)
• 35.8 Fix all linting errors (Laravel Pint, ESLint)
• 35.9 Run security audit (composer audit, npm audit)

36. Polish & UX

• 36.1 Add loading states (spinners, skeleton loaders)
• 36.2 Add error states (toast notifications, error pages)
• 36.3 Add empty states (no data placeholders)
• 36.4 Implement form validation feedback (inline errors, success messages)
• 36.5 Add confirmation modals for destructive actions (delete)
• 36.6 Implement responsive design (mobile-friendly tables, navigation)
• 36.7 Add keyboard shortcuts (ESC to close modals, etc.)
• 36.8 Add accessibility features (ARIA labels, focus management)
• 36.9 Test in multiple browsers (Chrome, Firefox, Safari)

37. Documentation & Deployment

• 37.1 Write README.md with setup instructions
• 37.2 Document environment variables (.env.example files)
• 37.3 Create Quick Start guide for managers (capacity → allocate → reports)
• 37.4 Document API authentication flow
• 37.5 Create deployment guide (Docker Compose production setup)
• 37.6 Add health check endpoints (/api/health)
• 37.7 Configure logging (Laravel logs to stdout, Svelte client errors to console)
• 37.8 Test full deployment workflow (fresh Docker Compose up)
• 37.9 Create superuser via seeder for initial login
• 37.10 Verify Nginx Proxy Manager routing

38. Final Verification

• 38.1 Run full test suite (unit + E2E) and verify all pass
• 38.2 Verify code coverage >70%
• 38.3 Run linters and fix all issues
• 38.4 Test complete user flow: capacity → allocate → log actuals → reports
• 38.5 Verify RBAC working for all 4 personas
• 38.6 Verify Redis caching working (check cache hit rate)
• 38.7 Verify API documentation accessible and accurate
• 38.8 Verify Docker Compose startup works cleanly
• 38.9 Verify database migrations and seeders work
• 38.10 Conduct final security review (no secrets in code, HTTPS enforced)