# aimhubio/aim architecture

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

- Interactive diagram: https://gitdiagram.com/aimhubio/aim
- Repository: https://github.com/aimhubio/aim

## Overview

Aim is a self-hosted ML experiment tracker: users instrument training to record run metadata, then query and compare runs through the SDK and web interface. Its main runtime spans framework integrations, run tracking, repository-backed persistence and indexing, an API server, and UI exploration; remote tracking, artifact storage, resource monitoring, and notifications extend that core. Relationships between sampled transport components are shown where the excerpts establish them; other links are documented by the README or left unverified where implementation was not sampled.

Main entry points: [`aim/sdk/run.py`](https://github.com/aimhubio/aim/blob/main/aim/sdk/run.py) (Run Tracking), [`aim/sdk/repo.py`](https://github.com/aimhubio/aim/blob/main/aim/sdk/repo.py) (Repository), [`aim/ext/transport/server.py`](https://github.com/aimhubio/aim/blob/main/aim/ext/transport/server.py) (Aim Server), [`aim/sdk/adapters`](https://github.com/aimhubio/aim/tree/main/aim/sdk/adapters) (Framework Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["Tracking SDK"]
  node_frameworks["Framework Adapters"]
  node_run["Run Tracking<br/>[run.py]"]
  node_training["Training Flow<br/>[training_flow.py]"]
end

subgraph group_persistence["Repository Data"]
  node_repo[("Repository<br/>[repo.py]")]
  node_indexer["Run Indexing<br/>[index_manager.py]"]
  node_locks["Run Locks<br/>[lock_manager.py]"]
  node_artifacts["Artifact Storage"]
  node_s3["S3 Artifacts<br/>[s3_storage.py]"]
end

subgraph group_serving["Serving and Remote"]
  node_api["Web API<br/>[views.py]"]
  node_webserver["Aim Server<br/>[server.py]"]
  node_handlers["Resource Handlers<br/>[handlers.py]"]
  node_client["Remote Client<br/>[client.py]"]
end

subgraph group_exploration["Query and UI"]
  node_query["Query Analysis<br/>[query_analyzer.py]"]
  node_ui["Exploration UI<br/>[App.tsx]"]
  node_notebook["Notebook Access<br/>[notebook.py]"]
end

subgraph group_operations["Operations and Integrations"]
  node_cli["CLI<br/>[cli.py]"]
  node_conversion["Tracker Conversion<br/>[commands.py]"]
  node_resource["Resource Tracking<br/>[tracker.py]"]
  node_notifications["Notifications<br/>[notifier.py]"]
end

node_ml_user(("ML User"))
node_external_store[("S3 Service")]

node_ml_user -->|"instruments training"| node_frameworks
node_frameworks -.->|"logs metadata"| node_run
node_ml_user -->|"tracks runs"| node_run
node_run -.->|"stores run data"| node_repo
node_training -.->|"supports training"| node_run
node_repo -.->|"indexes run data"| node_indexer
node_run -.->|"uses run locks"| node_locks
node_artifacts -->|"implements storage"| node_s3
node_s3 -->|"uploads artifacts"| node_external_store
node_ml_user -->|"starts tracker"| node_cli
node_cli -.->|"starts server"| node_webserver
node_webserver -->|"registers resources"| node_handlers
node_handlers -->|"opens repository"| node_repo
node_client -.->|"sends requests"| node_webserver
node_ml_user -->|"explores runs"| node_ui
node_ui -.->|"queries API"| node_api
node_api -.->|"reads run data"| node_repo
node_ml_user -->|"queries metadata"| node_query
node_ml_user -->|"analyzes runs"| node_notebook
node_ml_user -->|"migrates tracker data"| node_conversion
node_run -.->|"tracks system usage"| node_resource
node_run -.->|"alerts on progress"| node_notifications

click node_cli "https://github.com/aimhubio/aim/blob/main/aim/cli/cli.py"
click node_frameworks "https://github.com/aimhubio/aim/tree/main/aim/sdk/adapters"
click node_run "https://github.com/aimhubio/aim/blob/main/aim/sdk/run.py"
click node_training "https://github.com/aimhubio/aim/blob/main/aim/sdk/training_flow.py"
click node_repo "https://github.com/aimhubio/aim/blob/main/aim/sdk/repo.py"
click node_indexer "https://github.com/aimhubio/aim/blob/main/aim/sdk/index_manager.py"
click node_locks "https://github.com/aimhubio/aim/blob/main/aim/sdk/lock_manager.py"
click node_artifacts "https://github.com/aimhubio/aim/blob/main/aim/storage/artifacts/artifact_storage.py"
click node_s3 "https://github.com/aimhubio/aim/blob/main/aim/storage/artifacts/s3_storage.py"
click node_query "https://github.com/aimhubio/aim/blob/main/aim/sdk/query_analyzer.py"
click node_api "https://github.com/aimhubio/aim/blob/main/aim/web/api/views.py"
click node_webserver "https://github.com/aimhubio/aim/blob/main/aim/ext/transport/server.py"
click node_handlers "https://github.com/aimhubio/aim/blob/main/aim/ext/transport/handlers.py"
click node_client "https://github.com/aimhubio/aim/blob/main/aim/ext/transport/client.py"
click node_ui "https://github.com/aimhubio/aim/blob/main/aim/web/ui/src/App.tsx"
click node_notebook "https://github.com/aimhubio/aim/blob/main/aim/ext/notebook/notebook.py"
click node_conversion "https://github.com/aimhubio/aim/blob/main/aim/cli/convert/commands.py"
click node_resource "https://github.com/aimhubio/aim/blob/main/aim/ext/resource/tracker.py"
click node_notifications "https://github.com/aimhubio/aim/blob/main/aim/ext/notifier/notifier.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_frameworks,node_run,node_training,node_ml_user toneBlue
class node_repo,node_indexer,node_locks,node_artifacts,node_s3,node_external_store toneAmber
class node_api,node_webserver,node_handlers,node_client toneMint
class node_query,node_ui,node_notebook toneRose
class node_cli,node_conversion,node_resource,node_notifications toneIndigo
```

## Components

### Tracking SDK

- [Framework Adapters](https://github.com/aimhubio/aim/tree/main/aim/sdk/adapters): `aim/sdk/adapters`
- [Run Tracking](https://github.com/aimhubio/aim/blob/main/aim/sdk/run.py): `aim/sdk/run.py`
- [Training Flow](https://github.com/aimhubio/aim/blob/main/aim/sdk/training_flow.py): `aim/sdk/training_flow.py`

### Repository Data

- [Repository](https://github.com/aimhubio/aim/blob/main/aim/sdk/repo.py): `aim/sdk/repo.py`
- [Run Indexing](https://github.com/aimhubio/aim/blob/main/aim/sdk/index_manager.py): `aim/sdk/index_manager.py`
- [Run Locks](https://github.com/aimhubio/aim/blob/main/aim/sdk/lock_manager.py): `aim/sdk/lock_manager.py`
- [Artifact Storage](https://github.com/aimhubio/aim/blob/main/aim/storage/artifacts/artifact_storage.py): `aim/storage/artifacts/artifact_storage.py`
- [S3 Artifacts](https://github.com/aimhubio/aim/blob/main/aim/storage/artifacts/s3_storage.py): `aim/storage/artifacts/s3_storage.py`

### Serving and Remote

- [Web API](https://github.com/aimhubio/aim/blob/main/aim/web/api/views.py): `aim/web/api/views.py`
- [Aim Server](https://github.com/aimhubio/aim/blob/main/aim/ext/transport/server.py): `aim/ext/transport/server.py`
- [Resource Handlers](https://github.com/aimhubio/aim/blob/main/aim/ext/transport/handlers.py): `aim/ext/transport/handlers.py`
- [Remote Client](https://github.com/aimhubio/aim/blob/main/aim/ext/transport/client.py): `aim/ext/transport/client.py`

### Query and UI

- [Query Analysis](https://github.com/aimhubio/aim/blob/main/aim/sdk/query_analyzer.py): `aim/sdk/query_analyzer.py`
- [Exploration UI](https://github.com/aimhubio/aim/blob/main/aim/web/ui/src/App.tsx): `aim/web/ui/src/App.tsx`
- [Notebook Access](https://github.com/aimhubio/aim/blob/main/aim/ext/notebook/notebook.py): `aim/ext/notebook/notebook.py`

### Operations and Integrations

- [CLI](https://github.com/aimhubio/aim/blob/main/aim/cli/cli.py): `aim/cli/cli.py`
- [Tracker Conversion](https://github.com/aimhubio/aim/blob/main/aim/cli/convert/commands.py): `aim/cli/convert/commands.py`
- [Resource Tracking](https://github.com/aimhubio/aim/blob/main/aim/ext/resource/tracker.py): `aim/ext/resource/tracker.py`
- [Notifications](https://github.com/aimhubio/aim/blob/main/aim/ext/notifier/notifier.py): `aim/ext/notifier/notifier.py`

### Other components

- **ML User**
- **S3 Service**

## Connections

- ML User → Framework Adapters: instruments training (evidence: `README.md`)
- Framework Adapters → Run Tracking: logs metadata
- ML User → Run Tracking: tracks runs (evidence: `README.md`)
- Run Tracking → Repository: stores run data
- Training Flow → Run Tracking: supports training
- Repository → Run Indexing: indexes run data (evidence: `aim/sdk/index_manager.py`)
- Run Tracking → Run Locks: uses run locks
- Artifact Storage → S3 Artifacts: implements storage (evidence: `aim/storage/artifacts/s3_storage.py`)
- S3 Artifacts → S3 Service: uploads artifacts (evidence: `aim/storage/artifacts/s3_storage.py`)
- ML User → CLI: starts tracker (evidence: `README.md`)
- CLI → Aim Server: starts server
- Aim Server → Resource Handlers: registers resources (evidence: `aim/ext/transport/server.py`)
- Resource Handlers → Repository: opens repository (evidence: `aim/ext/transport/handlers.py`)
- Remote Client → Aim Server: sends requests
- ML User → Exploration UI: explores runs (evidence: `README.md`)
- Exploration UI → Web API: queries API
- Web API → Repository: reads run data
- ML User → Query Analysis: queries metadata (evidence: `README.md`)
- ML User → Notebook Access: analyzes runs (evidence: `README.md`)
- ML User → Tracker Conversion: migrates tracker data (evidence: `README.md`)
- Run Tracking → Resource Tracking: tracks system usage
- Run Tracking → Notifications: alerts on progress
