# privateaim/hub architecture

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

- Interactive diagram: https://gitdiagram.com/privateaim/hub
- Repository: https://github.com/privateaim/hub

## Overview

FLAME Hub coordinates federated analysis: users create projects and analyses in the web UI, the core API manages their configuration and participating nodes, and background workers build and distribute analysis images. Nodes execute analyses locally so underlying data stays at the institution; results and files are collected through storage, with logs and events handled separately. The README documents the product workflow and service capabilities; sampled controller code confirms core service wiring and storage, telemetry, and messenger service entry points. Some cross-service links reflect documented behavior rather than inspected implementation.

Main entry points: [`apps/server-core`](https://github.com/privateaim/hub/tree/master/apps/server-core) (Core API), [`apps/client-ui`](https://github.com/privateaim/hub/tree/master/apps/client-ui) (Web application), [`apps/server-core/src/app/modules/http/controller.ts`](https://github.com/privateaim/hub/blob/master/apps/server-core/src/app/modules/http/controller.ts) (Core domain services), [`apps/server-core-worker/src/app`](https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_ui["Web application"]
  node_projects["Projects and nodes"]
  node_analysis_ui["Analysis workspace"]
  node_admin_ui["Administration"]
end

subgraph group_coordination["Core coordination"]
  node_core_api["Core API"]
  node_http_controllers["HTTP controllers"]
  node_domain_services["Core domain services<br/>[controller.ts]"]
  node_core_db[("Core database")]
  node_registry["Registry management"]
end

subgraph group_execution["Analysis execution"]
  node_worker["Background worker"]
  node_analysis_builder["Analysis image builder"]
  node_distributor["Analysis distributor"]
  node_docker["Docker integration"]
end

subgraph group_services["Platform services"]
  node_storage["Storage service"]
  node_telemetry["Telemetry service"]
  node_messenger["Messenger service"]
end

subgraph group_infrastructure["External infrastructure"]
  node_authup["Authup identity"]
  node_broker["Message broker"]
  node_database[("SQL database")]
  node_object_store[("Object storage")]
  node_logs_backend[("VictoriaLogs")]
end

node_user(("Researcher / admin"))
node_institution_nodes{{"Institution nodes"}}

node_user -->|"uses"| node_ui
node_ui -->|"opens"| node_projects
node_ui -->|"opens"| node_analysis_ui
node_ui -->|"opens"| node_admin_ui
node_projects -->|"manages projects"| node_core_api
node_analysis_ui -->|"submits analysis"| node_core_api
node_admin_ui -->|"administers"| node_core_api
node_core_api -->|"routes requests"| node_http_controllers
node_http_controllers -->|"invokes"| node_domain_services
node_domain_services -->|"reads and writes"| node_core_db
node_domain_services -->|"manages registries"| node_registry
node_domain_services -->|"dispatches tasks"| node_worker
node_worker -->|"builds images"| node_analysis_builder
node_worker -->|"distributes analyses"| node_distributor
node_analysis_builder -->|"builds containers"| node_docker
node_distributor -->|"pushes images"| node_docker
node_distributor -->|"ships analysis"| node_institution_nodes
node_institution_nodes -.->|"uploads results"| node_storage
node_ui -->|"manages files"| node_storage
node_core_api -.->|"records events"| node_telemetry
node_core_api -.->|"exchanges messages"| node_messenger
node_core_api -.->|"authenticates"| node_authup
node_core_api -.->|"publishes tasks"| node_broker
node_worker -.->|"consumes tasks"| node_broker
node_core_db -->|"persists entities"| node_database
node_storage -->|"stores files"| node_object_store
node_telemetry -.->|"stores logs"| node_logs_backend

click node_ui "https://github.com/privateaim/hub/tree/master/apps/client-ui"
click node_projects "https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/projects"
click node_analysis_ui "https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/analyses"
click node_admin_ui "https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/admin"
click node_core_api "https://github.com/privateaim/hub/tree/master/apps/server-core"
click node_http_controllers "https://github.com/privateaim/hub/tree/master/apps/server-core/src/adapters/http/controllers"
click node_domain_services "https://github.com/privateaim/hub/blob/master/apps/server-core/src/app/modules/http/controller.ts"
click node_core_db "https://github.com/privateaim/hub/tree/master/apps/server-core/src/adapters/database"
click node_registry "https://github.com/privateaim/hub/tree/master/apps/server-core/src/app/components/registry"
click node_worker "https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app"
click node_analysis_builder "https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app/components/analysis-builder"
click node_distributor "https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app/components/analysis-distributor"
click node_docker "https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/adapters/docker"
click node_storage "https://github.com/privateaim/hub/tree/master/apps/server-storage"
click node_telemetry "https://github.com/privateaim/hub/tree/master/apps/server-telemetry"
click node_messenger "https://github.com/privateaim/hub/tree/master/apps/server-messenger"

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_ui,node_projects,node_analysis_ui,node_admin_ui toneBlue
class node_core_api,node_http_controllers,node_domain_services,node_core_db,node_registry toneAmber
class node_worker,node_analysis_builder,node_distributor,node_docker toneMint
class node_storage,node_telemetry,node_messenger toneRose
class node_authup,node_broker,node_database,node_object_store,node_logs_backend,node_user,node_institution_nodes toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/privateaim/hub/tree/master/apps/client-ui): `apps/client-ui`
- [Projects and nodes](https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/projects): `apps/client-ui/pages/projects`
- [Analysis workspace](https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/analyses): `apps/client-ui/pages/analyses`
- [Administration](https://github.com/privateaim/hub/tree/master/apps/client-ui/pages/admin): `apps/client-ui/pages/admin`

### Core coordination

- [Core API](https://github.com/privateaim/hub/tree/master/apps/server-core): `apps/server-core`
- [HTTP controllers](https://github.com/privateaim/hub/tree/master/apps/server-core/src/adapters/http/controllers): `apps/server-core/src/adapters/http/controllers`
- [Core domain services](https://github.com/privateaim/hub/blob/master/apps/server-core/src/app/modules/http/controller.ts): `apps/server-core/src/app/modules/http/controller.ts`
- [Core database](https://github.com/privateaim/hub/tree/master/apps/server-core/src/adapters/database): `apps/server-core/src/adapters/database`
- [Registry management](https://github.com/privateaim/hub/tree/master/apps/server-core/src/app/components/registry): `apps/server-core/src/app/components/registry`

### Analysis execution

- [Background worker](https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app): `apps/server-core-worker/src/app`
- [Analysis image builder](https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app/components/analysis-builder): `apps/server-core-worker/src/app/components/analysis-builder`
- [Analysis distributor](https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/app/components/analysis-distributor): `apps/server-core-worker/src/app/components/analysis-distributor`
- [Docker integration](https://github.com/privateaim/hub/tree/master/apps/server-core-worker/src/adapters/docker): `apps/server-core-worker/src/adapters/docker`

### Platform services

- [Storage service](https://github.com/privateaim/hub/tree/master/apps/server-storage): `apps/server-storage`
- [Telemetry service](https://github.com/privateaim/hub/tree/master/apps/server-telemetry): `apps/server-telemetry`
- [Messenger service](https://github.com/privateaim/hub/tree/master/apps/server-messenger): `apps/server-messenger`

### External infrastructure

- **Authup identity**
- **Message broker**
- **SQL database**
- **Object storage**
- **VictoriaLogs**

### Other components

- **Researcher / admin**
- **Institution nodes**

## Connections

- Researcher / admin → Web application: uses
- Web application → Projects and nodes: opens
- Web application → Analysis workspace: opens
- Web application → Administration: opens
- Projects and nodes → Core API: manages projects
- Analysis workspace → Core API: submits analysis
- Administration → Core API: administers
- Core API → HTTP controllers: routes requests
- HTTP controllers → Core domain services: invokes
- Core domain services → Core database: reads and writes
- Core domain services → Registry management: manages registries
- Core domain services → Background worker: dispatches tasks
- Background worker → Analysis image builder: builds images
- Background worker → Analysis distributor: distributes analyses
- Analysis image builder → Docker integration: builds containers
- Analysis distributor → Docker integration: pushes images
- Analysis distributor → Institution nodes: ships analysis
- Institution nodes → Storage service: uploads results
- Web application → Storage service: manages files
- Core API → Telemetry service: records events
- Core API → Messenger service: exchanges messages
- Core API → Authup identity: authenticates
- Core API → Message broker: publishes tasks
- Background worker → Message broker: consumes tasks
- Core database → SQL database: persists entities
- Storage service → Object storage: stores files
- Telemetry service → VictoriaLogs: stores logs