# databricks-solutions/lakebase-fastapi-app architecture

> Architecture diagram of the GitHub repository databricks-solutions/lakebase-fastapi-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/databricks-solutions/lakebase-fastapi-app
- Repository: https://github.com/databricks-solutions/lakebase-fastapi-app

## Overview

This is a FastAPI read API for orders stored in a Lakebase autoscaling Postgres table synced from Databricks sample data. The main flow is a client request through the versioned orders routes, a database session, and queries against the synced table; responses use order and pagination models. The app also exposes health checks and initializes the database engine and OAuth token refresh at startup. The README documents bundle provisioning and post-deploy access grants; their wiring is represented from documentation, while the database implementation excerpt is partial.

Main entry points: [`src/core/database.py`](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/core/database.py) (DB session layer), [`src/app.py`](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/app.py) (FastAPI app), [`src/routers/v1/orders.py`](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/orders.py) (Orders routes), [`src/routers/v1/__init__.py`](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/__init__.py) (V1 routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI app<br/>[app.py]"]
  node_api_router["API router<br/>[__init__.py]"]
  node_v1_router["V1 routes<br/>[__init__.py]"]
  node_health_route["Health route<br/>[healthcheck.py]"]
end

subgraph group_data["Order data"]
  node_orders_route["Orders routes<br/>[orders.py]"]
  node_order_models["Order models<br/>[orders.py]"]
  node_orders_table[("Synced orders table")]
end

subgraph group_connectivity["Database connectivity"]
  node_session["DB session layer<br/>[database.py]"]
  node_oauth["OAuth credentials<br/>[database.py]"]
  node_lakebase{{"Lakebase endpoint"}}
end

subgraph group_provisioning["Provisioning"]
  node_source_table[("UC source table")]
  node_bundle["Bundle provisioning<br/>[databricks.yml]"]
  node_grant_hook["Access grant hook"]
  node_service_principal(("App principal"))
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts"| node_api_router
node_api_router -->|"includes"| node_v1_router
node_v1_router -->|"dispatches"| node_orders_route
node_v1_router -->|"dispatches"| node_health_route
node_orders_route -->|"requests session"| node_session
node_orders_route -->|"validates and shapes"| node_order_models
node_orders_route -->|"queries"| node_orders_table
node_order_models -->|"maps"| node_orders_table
node_app -->|"initializes engine"| node_session
node_app -->|"starts token refresh"| node_session
node_session -->|"refreshes credentials"| node_oauth
node_oauth -->|"requests tokens"| node_lakebase
node_session -->|"connects"| node_lakebase
node_source_table -->|"syncs data"| node_orders_table
node_bundle -->|"runs post-deploy"| node_grant_hook
node_grant_hook -->|"grants read access"| node_service_principal
node_grant_hook -->|"connects as deployer"| node_lakebase

click node_app "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/app.py"
click node_api_router "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/__init__.py"
click node_v1_router "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/__init__.py"
click node_health_route "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/healthcheck.py"
click node_orders_route "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/orders.py"
click node_order_models "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/models/orders.py"
click node_session "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/core/database.py"
click node_oauth "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/core/database.py"
click node_bundle "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/databricks.yml"
click node_grant_hook "https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/scripts/grant_app_access.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_api_router,node_v1_router,node_health_route,node_client toneBlue
class node_orders_route,node_order_models,node_orders_table toneAmber
class node_session,node_oauth,node_lakebase toneMint
class node_source_table,node_bundle,node_grant_hook,node_service_principal toneRose
```

## Components

### API surface

- [FastAPI app](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/app.py): `src/app.py`
- [API router](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/__init__.py): `src/routers/__init__.py`
- [V1 routes](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/__init__.py): `src/routers/v1/__init__.py`
- [Health route](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/healthcheck.py): `src/routers/v1/healthcheck.py`

### Order data

- [Orders routes](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/routers/v1/orders.py): `src/routers/v1/orders.py`
- [Order models](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/models/orders.py): `src/models/orders.py`
- **Synced orders table**

### Database connectivity

- [DB session layer](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/core/database.py): `src/core/database.py`
- [OAuth credentials](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/src/core/database.py): `src/core/database.py`
- **Lakebase endpoint**

### Provisioning

- **UC source table**
- [Bundle provisioning](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/databricks.yml): `databricks.yml`
- [Access grant hook](https://github.com/databricks-solutions/lakebase-fastapi-app/blob/main/scripts/grant_app_access.py): `scripts/grant_app_access.py`
- **App principal**

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → API router: mounts
- API router → V1 routes: includes
- V1 routes → Orders routes: dispatches
- V1 routes → Health route: dispatches
- Orders routes → DB session layer: requests session
- Orders routes → Order models: validates and shapes
- Orders routes → Synced orders table: queries
- Order models → Synced orders table: maps
- FastAPI app → DB session layer: initializes engine
- FastAPI app → DB session layer: starts token refresh
- DB session layer → OAuth credentials: refreshes credentials
- OAuth credentials → Lakebase endpoint: requests tokens
- DB session layer → Lakebase endpoint: connects
- UC source table → Synced orders table: syncs data
- Bundle provisioning → Access grant hook: runs post-deploy
- Access grant hook → App principal: grants read access
- Access grant hook → Lakebase endpoint: connects as deployer