Data model

Source of truth

• Cloud Spanner is the authoritative data store.
• Interface is read-mostly and mirrors Spanner tables into response models.

Primary entities

The service exposes read APIs for the following domains (mapped to Spanner tables):

• Instances
• Organizations
• Clinics
• Households
• Contacts
• Patients
• Team members
• Appointments
• Appointment types
• Appointment statuses
• Invoices and invoice lines
• Products
• Reports (derived from invoice and invoice line data)

Write exceptions

Two legacy update endpoints write to Spanner:

• appointment-types/update updates AppointmentTypes.is_wellness.
• appointment-statuses/update updates AppointmentStatuses.status.

Schema management

• Spanner schema changes are managed via Liquibase under db/liquibase/.
• Response schemas live in services/interface/models/ and should stay in sync with Spanner tables and query projections.

Data ownership

• Interface does not own data; it only reads Spanner data owned by the core platform services.