Architecture

Interface is a Python 3.13 FastAPI service that sits between the Bubble app and Cloud Spanner, exposing a read-mostly HTTP API.

System context

Bubble app ---> Interface (FastAPI) ---> Cloud Spanner
                  |-> Secret Manager (API key, Sentry DSN)
                  |-> Sentry (errors + traces)

Request flow

1. Bubble sends a request with the X-API-Key header.
2. APIKeyMiddleware validates the header (health checks are exempt).
3. The endpoint builds parameterized Spanner SQL using QueryBuilder.
4. Spanner executes a read-only transaction and returns rows.
5. Results are mapped to Pydantic models and returned as JSON.

Write exceptions

Interface is read-mostly. The only write paths are legacy updates for appointment types and appointment statuses.

Components

• services/interface/main.py: app setup, middleware, CORS, Spanner lifecycle.
• services/interface/routers/: API version routing (v1 and v2).
• services/interface/api/: endpoint implementations.
• services/interface/core/query_builder.py: query assembly and parameter binding.
• services/interface/models/: request/response models.
• services/interface/middleware/api_key_middleware.py: API key enforcement.
• packages/python/common/: Spanner client and Secret Manager helpers.

Reliability and scaling

• Spanner pool is warmed at startup and cleared on shutdown.
• The production container runs granian with a single worker by default.
• Changes must preserve response shapes and pagination semantics due to legacy clients.