Skip to main content

ADR-0001: Facilities Service

  • Status: Accepted
  • Date: 2025-07-21
  • Author: @digiwedge/engineering
  • Supersedes: Facility tables embedded in tee-sheet

Context​

The tee-sheet module originally defined FacilityResource and related tables inside libs/prisma/tee-sheet-data. Sport Club Ledger (SCL) lacked a matching model, preventing other modules from sharing facility data without coupling directly to tee-sheet.

This blocked:

  • Cross-module reporting
  • Integration with Member Club Admin (MCA)
  • Shared maintenance tracking

Decision​

Create a dedicated Facilities Service to manage all facility resources with:

  1. Dedicated Prisma Schema containing:

    • FacilityResource - physical assets
    • MaintenanceLog - maintenance tracking
    • ResourceUsage - booking assignments

  2. REST and GraphQL APIs so tee-sheet, SCL, and MCA can reference facilities without owning the data

  3. Multi-tenant Architecture with required tenantId scoping on all operations

Implementation​

ComponentLocation
Prisma Schemalibs/prisma/facilities-data
Service Modulelibs/facilities/facilities-service
API Applicationapps/facilities/facilities-api
Documentationapps/facilities/facilities-docs

Consequences​

Positive​

  • Decoupling: Tee-sheet no longer owns facility data
  • Reusability: SCL and MCA can consume the same API
  • Consistency: Single source of truth for facilities
  • Maintainability: Clear ownership and boundaries

Negative​

  • Network Overhead: Cross-service calls instead of direct DB access
  • Migration Complexity: Data migration from tee-sheet required
  • Deployment Dependency: Facilities API must be available

Migration Path​

  1. Deploy Facilities API with empty database
  2. Run migration scripts to copy data from tee-sheet
  3. Update tee-sheet to call Facilities API
  4. Drop facility tables from tee-sheet schema
  5. Update SCL to use Facilities API

Follow-ups​

  1. ✅ Create facilities-data Prisma library
  2. ✅ Create facilities-service NestJS module
  3. ✅ Create facilities-api application
  4. ✅ Add maintenance log and resource usage APIs
  5. ⏳ Write migration scripts for tee-sheet data
  6. ⏳ Publish client libraries for SCL and MCA