# minnelab/maia architecture

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

- Interactive diagram: https://gitdiagram.com/minnelab/maia
- Repository: https://github.com/minnelab/maia

## Overview

MAIA Toolkit deploys and manages a Kubernetes-based collaborative medical-AI platform. The main researcher workflow is to authenticate to the dashboard, manage users and projects, configure namespaces and compute resources, then use the platform’s research services; Kubernetes runs the resulting workloads. The repository also contains installation/deployment tooling and GPU-admission components. The dashboard authentication and user-management links are supported by sampled source; other dashboard capabilities are represented from the README and file tree, so their internal call wiring is not asserted.

Main entry points: [`docker/GPU_Booking_Admission_Controller/webhook.go`](https://github.com/minnelab/maia/blob/master/docker/GPU_Booking_Admission_Controller/webhook.go) (GPU admission), [`MAIA/dashboard/core/keycloak_auth.py`](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/core/keycloak_auth.py) (OIDC authentication), [`MAIA/dashboard/apps/models.py`](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/models.py) (MAIA user data), [`MAIA/dashboard/apps/user_management/services.py`](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/user_management/services.py) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard<br/>[views.py]"]
  node_auth["OIDC authentication<br/>[keycloak_auth.py]"]
end

subgraph group_platform["Platform management"]
  node_user_management["User management<br/>[services.py]"]
  node_user_store[("MAIA user data<br/>[models.py]")]
  node_project_management["Projects<br/>[services.py]"]
  node_namespaces["Namespaces<br/>[views.py]"]
  node_resources["Compute resources<br/>[views.py]"]
  node_gpu_scheduler["GPU scheduling<br/>[views.py]"]
end

subgraph group_research["Research services"]
  node_segmentation["Segmentation portal<br/>[views.py]"]
  node_agent_api["Agent API<br/>[views.py]"]
  node_mcp["MCP server<br/>[maia_mcp_server.py]"]
end

subgraph group_operations["Cluster operations"]
  node_installer["Platform installer<br/>[MAIA_Install.py]"]
  node_deployment_tools["Deployment tools<br/>[maia_core.py]"]
  node_admission["GPU admission<br/>[webhook.go]"]
  node_pod_terminator["Pod terminator<br/>[controller.py]"]
end

node_researcher(("Researcher"))
node_keycloak["Keycloak"]
node_kubernetes["Kubernetes"]
node_gpu_api["Scheduling API"]

node_researcher -->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"authenticates via"| node_auth
node_auth -->|"fetches signing keys"| node_keycloak
node_auth -->|"looks up user"| node_user_store
node_user_management -->|"reads and writes"| node_user_store
node_user_management -->|"syncs users and groups"| node_keycloak
node_project_management -->|"stores projects"| node_user_store
node_installer -->|"runs setup"| node_deployment_tools
node_deployment_tools -->|"manages cluster"| node_kubernetes
node_admission -->|"checks schedulability"| node_gpu_api
node_admission -->|"queries GPU status"| node_gpu_api
node_admission -->|"requests random deletion"| node_pod_terminator
node_pod_terminator -->|"lists and recreates pods"| node_kubernetes
node_segmentation -.->|"runs on platform"| node_kubernetes
node_agent_api -.->|"optional integration"| node_mcp

click node_dashboard_ui "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/home/views.py"
click node_auth "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/core/keycloak_auth.py"
click node_user_management "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/user_management/services.py"
click node_user_store "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/models.py"
click node_project_management "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/user_management/services.py"
click node_namespaces "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/namespaces/views.py"
click node_resources "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/resources/views.py"
click node_gpu_scheduler "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/gpu_scheduler/views.py"
click node_segmentation "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/maia_segmentation_portal/views.py"
click node_agent_api "https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/agent_api/views.py"
click node_mcp "https://github.com/minnelab/maia/blob/master/mcp_server/maia_mcp_server.py"
click node_installer "https://github.com/minnelab/maia/blob/master/MAIA_scripts/MAIA_Install.py"
click node_deployment_tools "https://github.com/minnelab/maia/blob/master/MAIA/maia_core.py"
click node_admission "https://github.com/minnelab/maia/blob/master/docker/GPU_Booking_Admission_Controller/webhook.go"
click node_pod_terminator "https://github.com/minnelab/maia/blob/master/docker/GPU_Booking_Pod_Terminator/controller.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_dashboard_ui,node_auth toneBlue
class node_user_management,node_user_store,node_project_management,node_namespaces,node_resources,node_gpu_scheduler toneAmber
class node_segmentation,node_agent_api,node_mcp,node_gpu_api toneMint
class node_installer,node_deployment_tools,node_admission,node_pod_terminator toneRose
class node_researcher,node_keycloak,node_kubernetes toneIndigo
```

## Components

### Dashboard

- [Dashboard](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/home/views.py): `MAIA/dashboard/apps/home/views.py`
- [OIDC authentication](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/core/keycloak_auth.py): `MAIA/dashboard/core/keycloak_auth.py`

### Platform management

- [User management](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/user_management/services.py): `MAIA/dashboard/apps/user_management/services.py`
- [MAIA user data](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/models.py): `MAIA/dashboard/apps/models.py`
- [Projects](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/user_management/services.py): `MAIA/dashboard/apps/user_management/services.py`
- [Namespaces](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/namespaces/views.py): `MAIA/dashboard/apps/namespaces/views.py`
- [Compute resources](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/resources/views.py): `MAIA/dashboard/apps/resources/views.py`
- [GPU scheduling](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/gpu_scheduler/views.py): `MAIA/dashboard/apps/gpu_scheduler/views.py`

### Research services

- [Segmentation portal](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/maia_segmentation_portal/views.py): `MAIA/dashboard/apps/maia_segmentation_portal/views.py`
- [Agent API](https://github.com/minnelab/maia/blob/master/MAIA/dashboard/apps/agent_api/views.py): `MAIA/dashboard/apps/agent_api/views.py`
- [MCP server](https://github.com/minnelab/maia/blob/master/mcp_server/maia_mcp_server.py): `mcp_server/maia_mcp_server.py`

### Cluster operations

- [Platform installer](https://github.com/minnelab/maia/blob/master/MAIA_scripts/MAIA_Install.py): `MAIA_scripts/MAIA_Install.py`
- [Deployment tools](https://github.com/minnelab/maia/blob/master/MAIA/maia_core.py): `MAIA/maia_core.py`
- [GPU admission](https://github.com/minnelab/maia/blob/master/docker/GPU_Booking_Admission_Controller/webhook.go): `docker/GPU_Booking_Admission_Controller/webhook.go`
- [Pod terminator](https://github.com/minnelab/maia/blob/master/docker/GPU_Booking_Pod_Terminator/controller.py): `docker/GPU_Booking_Pod_Terminator/controller.py`

### Other components

- **Researcher**
- **Keycloak**
- **Kubernetes**
- **Scheduling API**

## Connections

- Researcher → Dashboard: uses
- Dashboard → OIDC authentication: authenticates via
- OIDC authentication → Keycloak: fetches signing keys
- OIDC authentication → MAIA user data: looks up user
- User management → MAIA user data: reads and writes
- User management → Keycloak: syncs users and groups
- Projects → MAIA user data: stores projects
- Platform installer → Deployment tools: runs setup
- Deployment tools → Kubernetes: manages cluster
- GPU admission → Scheduling API: checks schedulability
- GPU admission → Scheduling API: queries GPU status
- GPU admission → Pod terminator: requests random deletion
- Pod terminator → Kubernetes: lists and recreates pods
- Segmentation portal → Kubernetes: runs on platform
- Agent API → MCP server: optional integration