headroom/openspec/changes/archive/2026-03-22-implement-actuals-tracking/design.md

Architecture Overview

The actuals tracking feature follows the existing patterns in the Headroom application:

• Backend: Laravel API with controller, service, model, and resource classes
• Frontend: SvelteKit with TypeScript, using service layer for API calls
• Database: MySQL with UUID primary keys and foreign key constraints

Data Model

Database Schema

actuals
├── id (UUID, PK)
├── project_id (UUID, FK → projects.id)
├── team_member_id (UUID, FK → team_members.id, nullable for untracked)
├── month (DATE, stored as first day of month)
├── hours_logged (DECIMAL 8,2)
├── notes (TEXT, nullable)
├── created_at (TIMESTAMP)
└── updated_at (TIMESTAMP)

Indexes:
- idx_actuals_project_month (project_id, month)
- idx_actuals_member_month (team_member_id, month)

Unique Constraint

The combination of (project_id, team_member_id, month) is the natural key but no explicit unique constraint is enforced. The application handles upserts by checking for existing records.

API Design

Endpoints

Method	Endpoint	Description
GET	/api/actuals	List actuals grid for month (paginated)
POST	/api/actuals	Create/append actual hours
GET	/api/actuals/{id}	Get single actual with variance
PUT	/api/actuals/{id}	Update actual hours (replace)
DELETE	/api/actuals/{id}	Delete actual

Index Endpoint Parameters

month: required, format Y-m
project_ids[]: optional, array of UUIDs
team_member_ids[]: optional, array of UUIDs
include_inactive: optional, boolean
search: optional, string
page: optional, integer
per_page: optional, integer (1-250, default 25)

Response Format

{
  "data": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "project": { "id", "code", "title", "status", "is_active" },
      "team_member_id": "uuid",
      "team_member": { "id", "name", "is_active" },
      "month": "2024-03",
      "allocated_hours": "80.00",
      "actual_hours": "75.50",
      "variance_percentage": -5.6,
      "variance_display": null,
      "variance_indicator": "green",
      "notes": null,
      "is_readonly": false
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

Frontend Architecture

Components

• Page: src/routes/actuals/+page.svelte - Main grid page
• Services: src/lib/services/actualsService.ts - API client
• Types: src/lib/types/actuals.ts - TypeScript interfaces

State Management

Uses Svelte 5 runes ($state, $derived) for reactive state:

• Filter state: currentPeriod, selectedProjectIds, selectedMemberIds, includeInactive, searchQuery
• Pagination state: currentPage, totalPages, totalItems, perPage
• Modal state: showModal, selectedCell, formHours, formNotes

URL Synchronization

Filter state is synchronized to URL query parameters for shareability and browser history.

Business Rules

Validation Rules

1. Future months: Cannot log hours for months after the current month
2. Completed projects: Cannot log hours to projects with status Done, Cancelled, or Closed
   • Configurable via ALLOW_ACTUALS_ON_INACTIVE_PROJECTS env variable
3. Hours must be positive: Minimum 0, stored as decimal

Variance Calculation

if allocated <= 0:
  if actual > 0: variance = infinity (∞%)
  else: variance = 0%
else:
  variance = ((actual - allocated) / allocated) * 100

Indicator Thresholds

Variance	Indicator	Color
±5%	green	Match
±20%	yellow	Warning
>20%	red	Alert
no data	gray	N/A

Security Considerations

• JWT authentication required for all endpoints
• Authorization handled at middleware level (existing patterns)
• Input validation via Laravel Validator
• SQL injection prevented via Eloquent ORM

Performance Considerations

• Cartesian grid built in-memory after fetching filtered projects and members
• Pagination applied to final grid rows (not database level)
• Indexes on (project_id, month) and (team_member_id, month) for efficient lookups
• Eager loading of relationships via Eloquent with()

Configuration

// config/actuals.php
return [
    'allow_actuals_on_inactive_projects' => env('ALLOW_ACTUALS_ON_INACTIVE_PROJECTS', false),
];