# cosbif/medicam-server architecture

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

- Interactive diagram: https://gitdiagram.com/cosbif/medicam-server
- Repository: https://github.com/cosbif/medicam-server

## Overview

Medicam Server is a Radxa camera backend with a protected local HTTP API and an always-available BLE provisioning service. The main workflow is owner app → BLE QR-based authorization and Wi-Fi setup → local authenticated API → recording and media access; companion capabilities include camera preview, health diagnostics, version reporting, storage retention, and signed OTA. Edges reflect excerpted calls or explicit README workflow statements; deployment and service-tunnel behavior is documented, but implementation wiring not shown here is omitted.

Main entry points: [`app/routes.py`](https://github.com/cosbif/medicam-server/blob/main/app/routes.py) (HTTP API), [`app/diagnostics.py`](https://github.com/cosbif/medicam-server/blob/main/app/diagnostics.py) (Health and tests), [`app/camera.py`](https://github.com/cosbif/medicam-server/blob/main/app/camera.py) (Camera recording), [`app/update_control.py`](https://github.com/cosbif/medicam-server/blob/main/app/update_control.py) (Update coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Device access"]
  node_ble["BLE provisioning"]
  node_device_utils["Device auth and Wi-Fi<br/>[utils.py]"]
  node_http_api["HTTP API<br/>[routes.py]"]
  node_server["API server<br/>[main.py]"]
end

subgraph group_media["Capture and media"]
  node_camera["Camera recording<br/>[camera.py]"]
  node_audio["Audio capture<br/>[audio.py]"]
  node_preview["Live preview<br/>[preview.py]"]
  node_library["Media library<br/>[utils.py]"]
end

subgraph group_operations["Operations"]
  node_storage["Storage policy<br/>[storage_manager.py]"]
  node_diagnostics["Health and tests<br/>[diagnostics.py]"]
  node_versions["Version reporting<br/>[version_info.py]"]
  node_update_api["Update coordination<br/>[update_control.py]"]
  node_updater["Signed OTA<br/>[updater.py]"]
  node_ble_manager["BLE service manager<br/>[manage_ble.py]"]
  node_service_tunnel["Service SSH tunnel"]
  node_ota_activator["Privileged OTA activator"]
end

node_owner(("Owner app"))

node_owner -->|"provisions device"| node_ble
node_ble -->|"uses device state"| node_device_utils
node_owner -->|"uses local API"| node_http_api
node_server -->|"serves routes"| node_http_api
node_http_api -->|"controls capture"| node_camera
node_http_api -->|"uses audio"| node_audio
node_http_api -->|"requests health"| node_diagnostics
node_http_api -->|"serves preview"| node_preview
node_http_api -->|"serves media"| node_library
node_http_api -->|"reads policy"| node_storage
node_http_api -->|"starts update"| node_update_api
node_http_api -->|"reads update status"| node_updater
node_http_api -->|"reports version"| node_versions
node_camera -->|"captures audio"| node_audio
node_camera -->|"coordinates preview"| node_preview
node_camera -->|"indexes recordings"| node_library
node_diagnostics -->|"checks recording"| node_camera
node_diagnostics -->|"tests audio"| node_audio
node_diagnostics -->|"pauses preview"| node_preview
node_diagnostics -->|"checks capacity"| node_storage
node_diagnostics -->|"reports version"| node_versions
node_update_api -->|"reserves device"| node_diagnostics
node_update_api -->|"checks recording"| node_camera
node_update_api -->|"queues update"| node_updater
node_updater -.->|"requests activation"| node_ota_activator
node_ble_manager -.->|"monitors service"| node_ble
node_service_tunnel -.->|"operator access"| node_owner

click node_ble "https://github.com/cosbif/medicam-server/blob/main/app/bluetooth_provision.py"
click node_device_utils "https://github.com/cosbif/medicam-server/blob/main/app/utils.py"
click node_http_api "https://github.com/cosbif/medicam-server/blob/main/app/routes.py"
click node_server "https://github.com/cosbif/medicam-server/blob/main/app/main.py"
click node_camera "https://github.com/cosbif/medicam-server/blob/main/app/camera.py"
click node_audio "https://github.com/cosbif/medicam-server/blob/main/app/audio.py"
click node_preview "https://github.com/cosbif/medicam-server/blob/main/app/preview.py"
click node_library "https://github.com/cosbif/medicam-server/blob/main/app/utils.py"
click node_storage "https://github.com/cosbif/medicam-server/blob/main/app/storage_manager.py"
click node_diagnostics "https://github.com/cosbif/medicam-server/blob/main/app/diagnostics.py"
click node_versions "https://github.com/cosbif/medicam-server/blob/main/app/version_info.py"
click node_update_api "https://github.com/cosbif/medicam-server/blob/main/app/update_control.py"
click node_updater "https://github.com/cosbif/medicam-server/blob/main/app/updater.py"
click node_ble_manager "https://github.com/cosbif/medicam-server/blob/main/app/manage_ble.py"
click node_service_tunnel "https://github.com/cosbif/medicam-server/blob/main/deploy/systemd/medicam-service-tunnel.service"
click node_ota_activator "https://github.com/cosbif/medicam-server/blob/main/scripts/medicam_ota_activate.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_ble,node_device_utils,node_http_api,node_server toneBlue
class node_camera,node_audio,node_preview,node_library toneAmber
class node_storage,node_diagnostics,node_versions,node_update_api,node_updater,node_ble_manager,node_service_tunnel,node_ota_activator toneMint
class node_owner toneIndigo
```

## Components

### Device access

- [BLE provisioning](https://github.com/cosbif/medicam-server/blob/main/app/bluetooth_provision.py): `app/bluetooth_provision.py`
- [Device auth and Wi-Fi](https://github.com/cosbif/medicam-server/blob/main/app/utils.py): `app/utils.py`
- [HTTP API](https://github.com/cosbif/medicam-server/blob/main/app/routes.py): `app/routes.py`
- [API server](https://github.com/cosbif/medicam-server/blob/main/app/main.py): `app/main.py`

### Capture and media

- [Camera recording](https://github.com/cosbif/medicam-server/blob/main/app/camera.py): `app/camera.py`
- [Audio capture](https://github.com/cosbif/medicam-server/blob/main/app/audio.py): `app/audio.py`
- [Live preview](https://github.com/cosbif/medicam-server/blob/main/app/preview.py): `app/preview.py`
- [Media library](https://github.com/cosbif/medicam-server/blob/main/app/utils.py): `app/utils.py`

### Operations

- [Storage policy](https://github.com/cosbif/medicam-server/blob/main/app/storage_manager.py): `app/storage_manager.py`
- [Health and tests](https://github.com/cosbif/medicam-server/blob/main/app/diagnostics.py): `app/diagnostics.py`
- [Version reporting](https://github.com/cosbif/medicam-server/blob/main/app/version_info.py): `app/version_info.py`
- [Update coordination](https://github.com/cosbif/medicam-server/blob/main/app/update_control.py): `app/update_control.py`
- [Signed OTA](https://github.com/cosbif/medicam-server/blob/main/app/updater.py): `app/updater.py`
- [BLE service manager](https://github.com/cosbif/medicam-server/blob/main/app/manage_ble.py): `app/manage_ble.py`
- [Service SSH tunnel](https://github.com/cosbif/medicam-server/blob/main/deploy/systemd/medicam-service-tunnel.service): `deploy/systemd/medicam-service-tunnel.service`
- [Privileged OTA activator](https://github.com/cosbif/medicam-server/blob/main/scripts/medicam_ota_activate.py): `scripts/medicam_ota_activate.py`

### Other components

- **Owner app**

## Connections

- Owner app → BLE provisioning: provisions device (evidence: `README.md`)
- BLE provisioning → Device auth and Wi-Fi: uses device state (evidence: `app/bluetooth_provision.py`)
- Owner app → HTTP API: uses local API (evidence: `README.md`)
- API server → HTTP API: serves routes (evidence: `app/main.py`)
- HTTP API → Camera recording: controls capture (evidence: `app/routes.py`)
- HTTP API → Audio capture: uses audio (evidence: `app/routes.py`)
- HTTP API → Health and tests: requests health (evidence: `app/routes.py`)
- HTTP API → Live preview: serves preview (evidence: `app/routes.py`)
- HTTP API → Media library: serves media (evidence: `app/routes.py`)
- HTTP API → Storage policy: reads policy (evidence: `app/routes.py`)
- HTTP API → Update coordination: starts update (evidence: `app/routes.py`)
- HTTP API → Signed OTA: reads update status (evidence: `app/routes.py`)
- HTTP API → Version reporting: reports version (evidence: `app/routes.py`)
- Camera recording → Audio capture: captures audio (evidence: `app/camera.py`)
- Camera recording → Live preview: coordinates preview (evidence: `app/camera.py`)
- Camera recording → Media library: indexes recordings (evidence: `app/camera.py`)
- Health and tests → Camera recording: checks recording (evidence: `app/diagnostics.py`)
- Health and tests → Audio capture: tests audio (evidence: `app/diagnostics.py`)
- Health and tests → Live preview: pauses preview (evidence: `app/diagnostics.py`)
- Health and tests → Storage policy: checks capacity (evidence: `app/diagnostics.py`)
- Health and tests → Version reporting: reports version (evidence: `app/diagnostics.py`)
- Update coordination → Health and tests: reserves device (evidence: `app/update_control.py`)
- Update coordination → Camera recording: checks recording (evidence: `app/update_control.py`)
- Update coordination → Signed OTA: queues update (evidence: `app/update_control.py`)
- Signed OTA → Privileged OTA activator: requests activation
- BLE service manager → BLE provisioning: monitors service (evidence: `README.md`)
- Service SSH tunnel → Owner app: operator access (evidence: `README.md`)
