Skip to main content

FS Garage Utilisation (BE) Architecture

System Overview​

PocketBase serves collections and custom JS hooks. Utilisation joins published allocations with external Timesheet API data to produce scorecard snapshots stored as JSON.

Architecture Diagram​

graph TB
    FrontendApp["Frontend<br/>base-fs-garage-fe"]
    UtilisationHooks["pb_hooks<br/>utilisation + allocations"]
    PublishedAllocations["allocations<br/>published weeks"]
    TimesheetApi["External Timesheet API"]
    UtilisationSnapshots["utilisation_snapshots<br/>scorecard JSON"]

    FrontendApp -->|"GET scorecard / POST run"| UtilisationHooks
    FrontendApp -->|"publish / copy-forward"| UtilisationHooks
    PublishedAllocations -->|"planned hours input"| UtilisationHooks
    TimesheetApi -->|"actual hours on run"| UtilisationHooks
    UtilisationHooks -->|"writes computed snapshot"| UtilisationSnapshots

How to read this diagram​

Arrows mean flow / dependency / "talks to", not button clicks. Each arrow label says what happens on that step.

Core Components​

Collections​

  • users / projects with timesheet bridge IDs
  • allocations - weekly planned hours
  • utilisation_snapshots - computed scorecard JSON

Hooks​

Copy patterns from weekly_hook.pb.js (routerAdd, $app queries, JSON responses).

Planned utilisation hooks: allocations.pb.js, utilisation.pb.js, utilisation-calc.js.

Data Flow​

  1. Publish allocations for a week
  2. POST /api/utilisation/run pulls Timesheet actuals
  3. BE computes snapshot (including unloggedHours)
  4. FE reads GET /api/utilisation/scorecard (sparklines from prior snapshots)

Design Decisions​

  • Calc logic in BE hooks only - never push math to FE
  • Do not store full timesheet as source of truth
  • pb_schema.json is stale; trust pb_migrations/
  • Local PocketBase only for development (ADR-005)

Technology Stack​

LayerTechnology
RuntimePocketBase
DBSQLite
HooksJavaScript pb_hooks
Templatestemplates/ email templates

Next Steps​