# personicle/backend-data-api-v2 architecture

> Architecture diagram of the GitHub repository personicle/backend-data-api-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/personicle/backend-data-api-v2
- Repository: https://github.com/personicle/backend-data-api-v2

## Overview

Personicle’s data-access API serves datastreams, events, and their metadata. A request is authorized against an external service, then the API queries PostgreSQL; datastream requests also consult a schema-matching service. The README names `/request` and `/request/events`, while the sampled implementation exposes `/datastreams` and `/events`. The excerpts do not show the full datastream query path, so that database relationship is marked unverified; unsampled implementation details are not inferred.

Main entry points: [`db_connection.py`](https://github.com/personicle/backend-data-api-v2/blob/main/db_connection.py) (Database runtime), [`main.py`](https://github.com/personicle/backend-data-api-v2/blob/main/main.py) (Datastream endpoint), [`base_schema.py`](https://github.com/personicle/backend-data-api-v2/blob/main/base_schema.py) (Data schemas), [`config.py`](https://github.com/personicle/backend-data-api-v2/blob/main/config.py) (Service configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routes"]
  node_datastream_api["Datastream endpoint<br/>[main.py]"]
  node_events_api["Events endpoint<br/>[main.py]"]
  node_event_metadata_api["Event metadata<br/>[main.py]"]
  node_stream_metadata_api["Stream metadata<br/>[main.py]"]
end

subgraph group_domain["Data models"]
  node_schema_defs["Data schemas<br/>[base_schema.py]"]
end

subgraph group_storage["Persistence"]
  node_db_runtime["Database runtime<br/>[db_connection.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["External services"]
  node_configuration["Service configuration<br/>[config.py]"]
  node_auth_service["Authorization service"]
  node_schema_service["Schema service"]
end

node_client(("API client"))

node_client -->|"requests data"| node_datastream_api
node_client -->|"requests events"| node_events_api
node_client -.->|"requests metadata"| node_event_metadata_api
node_client -.->|"requests metadata"| node_stream_metadata_api
node_datastream_api -->|"checks access"| node_auth_service
node_events_api -->|"checks access"| node_auth_service
node_event_metadata_api -->|"checks access"| node_auth_service
node_stream_metadata_api -->|"checks access"| node_auth_service
node_datastream_api -->|"matches schema"| node_schema_service
node_stream_metadata_api -->|"looks up schema"| node_schema_service
node_datastream_api -.->|"queries data"| node_db_runtime
node_events_api -->|"fetches events"| node_db_runtime
node_event_metadata_api -->|"fetches metadata"| node_db_runtime
node_stream_metadata_api -->|"iterates metadata"| node_db_runtime
node_db_runtime -->|"connects to"| node_postgres
node_db_runtime -->|"reads settings"| node_configuration
node_datastream_api -->|"imports schemas"| node_schema_defs

click node_datastream_api "https://github.com/personicle/backend-data-api-v2/blob/main/main.py"
click node_events_api "https://github.com/personicle/backend-data-api-v2/blob/main/main.py"
click node_event_metadata_api "https://github.com/personicle/backend-data-api-v2/blob/main/main.py"
click node_stream_metadata_api "https://github.com/personicle/backend-data-api-v2/blob/main/main.py"
click node_schema_defs "https://github.com/personicle/backend-data-api-v2/blob/main/base_schema.py"
click node_db_runtime "https://github.com/personicle/backend-data-api-v2/blob/main/db_connection.py"
click node_configuration "https://github.com/personicle/backend-data-api-v2/blob/main/config.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_datastream_api,node_events_api,node_event_metadata_api,node_stream_metadata_api,node_client toneBlue
class node_schema_defs toneAmber
class node_db_runtime,node_postgres toneMint
class node_configuration,node_auth_service,node_schema_service toneRose
```

## Components

### API routes

- [Datastream endpoint](https://github.com/personicle/backend-data-api-v2/blob/main/main.py): `main.py`
- [Events endpoint](https://github.com/personicle/backend-data-api-v2/blob/main/main.py): `main.py`
- [Event metadata](https://github.com/personicle/backend-data-api-v2/blob/main/main.py): `main.py`
- [Stream metadata](https://github.com/personicle/backend-data-api-v2/blob/main/main.py): `main.py`

### Data models

- [Data schemas](https://github.com/personicle/backend-data-api-v2/blob/main/base_schema.py): `base_schema.py`

### Persistence

- [Database runtime](https://github.com/personicle/backend-data-api-v2/blob/main/db_connection.py): `db_connection.py`
- **PostgreSQL**

### External services

- [Service configuration](https://github.com/personicle/backend-data-api-v2/blob/main/config.py): `config.py`
- **Authorization service**
- **Schema service**

### Other components

- **API client**

## Connections

- API client → Datastream endpoint: requests data (evidence: `README.md`)
- API client → Events endpoint: requests events (evidence: `README.md`)
- API client → Event metadata: requests metadata
- API client → Stream metadata: requests metadata
- Datastream endpoint → Authorization service: checks access (evidence: `main.py`)
- Events endpoint → Authorization service: checks access (evidence: `main.py`)
- Event metadata → Authorization service: checks access (evidence: `main.py`)
- Stream metadata → Authorization service: checks access (evidence: `main.py`)
- Datastream endpoint → Schema service: matches schema (evidence: `main.py`)
- Stream metadata → Schema service: looks up schema (evidence: `main.py`)
- Datastream endpoint → Database runtime: queries data (evidence: `main.py`)
- Events endpoint → Database runtime: fetches events (evidence: `main.py`)
- Event metadata → Database runtime: fetches metadata (evidence: `main.py`)
- Stream metadata → Database runtime: iterates metadata (evidence: `main.py`)
- Database runtime → PostgreSQL: connects to (evidence: `db_connection.py`)
- Database runtime → Service configuration: reads settings (evidence: `db_connection.py`)
- Datastream endpoint → Data schemas: imports schemas (evidence: `main.py`)
