Architecture

Raven is a Python 3.13 ConnectRPC ASGI service that serves the desktop client using the Connect Protocol (JSON) over HTTP/2.

System context

Raven desktop app -> Raven (ConnectRPC/ASGI) -> Spanner
                         |-> Bubble APIs (login/SSO)
                         |-> Firebase Admin (custom tokens)
                         |-> Secret Manager (Bubble token, OIDC client id)

Service layout

services/raven/
  main.py            ASGI entrypoint + lifespan
  config/            Settings + .env loading
  core/              Domain logic (auth, search, SSO, repository)
  tests/             Unit and integration tests

Request flow

1. Desktop app calls an RPC method (Connect/JSON over HTTP/2).
2. AuthInterceptor verifies Firebase ID tokens and injects claims.
3. Raven delegates to core services (search engine, SSO, or pet benefits).
4. Responses are serialized as Connect Protocol JSON.

Components

• services/raven/main.py: ASGI entrypoint and lifespan handling.
• services/raven/core/runtime.py: Connect app wiring + lifecycle.
• services/raven/core/engine.py: patient search orchestration.
• services/raven/core/repository.py: Spanner queries + search indexes.
• services/raven/core/bubble_client.py: Bubble login + SSO.
• services/raven/core/auth.py: Firebase Admin token management.
• services/raven/core/interceptors.py: auth and request context.
• services/raven/core/sso_service.py: Microsoft OIDC validation and SSO login.
• services/raven/core/pet_benefits.py: Pet benefits aggregation.

Auth and identity

• All RPCs except Login, SSO, and SSOLogin require a Firebase ID token.
• AuthInterceptor validates the token and enforces an organization_id claim.
• Login and SSOLogin mint Firebase custom tokens and set org claims.

Patient search pipeline

1. QueryClassifier normalizes the raw query.
2. SearchQueryContext gates probes (code vs. name vs. contact matches).
3. SpannerPatientSearchRepository runs a multi-probe SQL query with index hints.
4. PatientSearchEngine dedupes, ranks, and maps results to proto messages.
5. Results are returned as PatientSearchResponse or streamed in batches.

Streaming search

• stream_patient_search uses a coordinator to manage START/CANCEL commands.
• Search results stream in phases: RUNNING, RESULTS, DONE, CANCELLED, ERROR.
• Batch sizing is controlled by SEARCH_STREAM_BATCH_SIZE.

SSO and login flow

• Bubble APIs validate credentials and return organization context.
• Microsoft OIDC validation runs only when MICROSOFT_CLIENT_ID is configured.
• Firebase Admin mints tokens and adds organization_id custom claims.

Pet benefits

• Pet benefits are resolved via Bubble tables in Spanner (bubble_pet, bubble_subscriptions, bubble_petBenefit, bubble_benefit, bubble_product).
• The service short-circuits to empty responses when membership data is missing.

Reliability and scaling

• Spanner pool is warmed at startup and cleared on shutdown.
• Cloud Run is configured for h2c (HTTP/2 cleartext) on port 8080.
• Search performance depends on required Spanner search indexes.
• Search queries use optional exact staleness to reduce tail latency.