Nest Engineering Docs
Raven

Overview

Python 3.13 ConnectRPC backend for the Raven desktop app

Raven is a Python 3.13 ConnectRPC service that powers the Raven desktop client (apps/raven/). It speaks the Connect Protocol (JSON) over HTTP/2 and exposes patient search, SSO, and related RPCs backed by Cloud Spanner.

Service profile

FieldValue
Codeservices/raven/
Packageraven-service
RuntimePython 3.13 (ConnectRPC/ASGI)
StatusActive
Primary ownerAkansh Divker
Secondary ownerNone
Primary consumerRaven desktop app
ProtocolConnect (JSON) over HTTP/2

Responsibilities

  • Serve ConnectRPC APIs for the Raven desktop app.
  • Perform patient search and related lookups in Spanner.
  • Handle login and SSO flows for the Raven client.
  • Stream search results for interactive UX in the desktop app.

Non-goals

  • General-purpose public API surface.
  • ETL ingestion or pipeline scheduling (handled by Stream/Handler).

Tech stack

  • Python 3.13 + connect-python (ConnectRPC) on ASGI.
  • Granian ASGI server with HTTP/2 (h2c) support.
  • Cloud Spanner via the shared async Spanner client.
  • Firebase Admin for ID token verification + custom token minting.
  • Bubble APIs via httpx with retry/backoff.
  • Microsoft OIDC validation via pyjwt + JWKS discovery.
  • Structured logging via common.logging_utils.

Code entrypoints

  • services/raven/main.py: ASGI entrypoint + lifespan orchestration.
  • services/raven/core/runtime.py: ConnectRPC handler wiring + lifecycle.
  • services/raven/core/engine.py: search orchestration and ranking.
  • services/raven/core/repository.py: Spanner SQL + index hints.
  • services/raven/core/sso_service.py: Microsoft SSO validation and login.
  • services/raven/core/pet_benefits.py: pet benefits aggregation.

Dependencies

  • Upstream: Raven desktop app.
  • Downstream: Cloud Spanner; Bubble APIs; Firebase Admin.
  • External: Secret Manager; Microsoft OIDC.

Last updated on

Ownership

Ownership and support model for Datalake

Architecture

System design and data flow for Raven