# koramyashwanthreddy/max architecture

> Architecture diagram of the GitHub repository koramyashwanthreddy/max, 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/koramyashwanthreddy/max
- Repository: https://github.com/koramyashwanthreddy/max

## Overview

MAX is presented in the README as a self-hosted personal AI platform; this repository state documents the platform foundation, configuration, identity, provider-neutral AI runtime, and model management. The main user workflow is to submit a request to the API, use the registered model/runtime capabilities to generate a response, and manage model lifecycle separately. Identity supplies owner/profile context, while core infrastructure provides application lifecycle and shared configuration. The tree contains additional domain directories, but the README marks later modules as out of scope; their wiring was not inspected.

Main entry points: [`src/max/api/router.py`](https://github.com/koramyashwanthreddy/max/blob/main/src/max/api/router.py) (API routing), [`src/max/models/services/manager.py`](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/manager.py) (Model manager), [`src/max/main.py`](https://github.com/koramyashwanthreddy/max/blob/main/src/max/main.py) (Application entry), [`src/max/identity/api/routes.py`](https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/api/routes.py) (Identity endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform foundation"]
  node_app["Application entry<br/>[main.py]"]
  node_api["API routing<br/>[router.py]"]
  node_config["Configuration<br/>[settings.py]"]
  node_core["Lifecycle services<br/>[application.py]"]
end

subgraph group_identity["Identity profile"]
  node_identity_routes["Identity endpoints<br/>[routes.py]"]
  node_identity_service["Identity service"]
  node_identity_store[("Identity repository<br/>[memory.py]")]
end

subgraph group_runtime["AI runtime"]
  node_ai_routes["Inference endpoints<br/>[routes.py]"]
  node_ai_manager["Runtime manager<br/>[manager.py]"]
  node_ai_registry["Runtime registry<br/>[registry.py]"]
  node_ai_stub["Stub runtime<br/>[stub.py]"]
end

subgraph group_models["Model management"]
  node_model_routes["Model endpoints<br/>[routes.py]"]
  node_model_manager["Model manager<br/>[manager.py]"]
  node_model_registry["Model registry<br/>[registry.py]"]
  node_model_loader["Model loaders<br/>[loaders.py]"]
  node_model_repo["Model repositories<br/>[repositories.py]"]
end

node_user(("API client"))

node_user -->|"sends requests"| node_app
node_app -->|"serves API"| node_api
node_app -->|"initializes"| node_core
node_api -->|"routes identity"| node_identity_routes
node_api -->|"routes inference"| node_ai_routes
node_api -->|"routes models"| node_model_routes
node_identity_routes -->|"handles identity"| node_identity_service
node_identity_service -->|"reads and writes"| node_identity_store
node_ai_routes -->|"requests inference"| node_ai_manager
node_ai_manager -->|"selects runtime"| node_ai_registry
node_ai_registry -->|"provides default"| node_ai_stub
node_model_routes -->|"manages models"| node_model_manager
node_model_manager -->|"uses registry"| node_model_registry
node_model_manager -->|"loads models"| node_model_loader
node_model_manager -->|"persists metadata"| node_model_repo
node_config -->|"configures"| node_app

click node_app "https://github.com/koramyashwanthreddy/max/blob/main/src/max/main.py"
click node_api "https://github.com/koramyashwanthreddy/max/blob/main/src/max/api/router.py"
click node_config "https://github.com/koramyashwanthreddy/max/blob/main/src/max/config/settings.py"
click node_core "https://github.com/koramyashwanthreddy/max/blob/main/src/max/core/application.py"
click node_identity_routes "https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/api/routes.py"
click node_identity_service "https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/services/identity_service.py"
click node_identity_store "https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/repositories/memory.py"
click node_ai_routes "https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/api/routes.py"
click node_ai_manager "https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/manager.py"
click node_ai_registry "https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/registry.py"
click node_ai_stub "https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/stub.py"
click node_model_routes "https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/api/routes.py"
click node_model_manager "https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/manager.py"
click node_model_registry "https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/registry.py"
click node_model_loader "https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/loaders.py"
click node_model_repo "https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/repositories.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_app,node_api,node_config,node_core,node_user toneBlue
class node_identity_routes,node_identity_service,node_identity_store toneAmber
class node_ai_routes,node_ai_manager,node_ai_registry,node_ai_stub toneMint
class node_model_routes,node_model_manager,node_model_registry,node_model_loader,node_model_repo toneRose
```

## Components

### Platform foundation

- [Application entry](https://github.com/koramyashwanthreddy/max/blob/main/src/max/main.py): `src/max/main.py`
- [API routing](https://github.com/koramyashwanthreddy/max/blob/main/src/max/api/router.py): `src/max/api/router.py`
- [Configuration](https://github.com/koramyashwanthreddy/max/blob/main/src/max/config/settings.py): `src/max/config/settings.py`
- [Lifecycle services](https://github.com/koramyashwanthreddy/max/blob/main/src/max/core/application.py): `src/max/core/application.py`

### Identity profile

- [Identity endpoints](https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/api/routes.py): `src/max/identity/api/routes.py`
- [Identity service](https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/services/identity_service.py): `src/max/identity/services/identity_service.py`
- [Identity repository](https://github.com/koramyashwanthreddy/max/blob/main/src/max/identity/repositories/memory.py): `src/max/identity/repositories/memory.py`

### AI runtime

- [Inference endpoints](https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/api/routes.py): `src/max/ai/api/routes.py`
- [Runtime manager](https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/manager.py): `src/max/ai/runtime/manager.py`
- [Runtime registry](https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/registry.py): `src/max/ai/runtime/registry.py`
- [Stub runtime](https://github.com/koramyashwanthreddy/max/blob/main/src/max/ai/runtime/stub.py): `src/max/ai/runtime/stub.py`

### Model management

- [Model endpoints](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/api/routes.py): `src/max/models/api/routes.py`
- [Model manager](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/manager.py): `src/max/models/services/manager.py`
- [Model registry](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/registry.py): `src/max/models/services/registry.py`
- [Model loaders](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/loaders.py): `src/max/models/services/loaders.py`
- [Model repositories](https://github.com/koramyashwanthreddy/max/blob/main/src/max/models/services/repositories.py): `src/max/models/services/repositories.py`

### Other components

- **API client**

## Connections

- API client → Application entry: sends requests
- Application entry → API routing: serves API
- Application entry → Lifecycle services: initializes
- API routing → Identity endpoints: routes identity
- API routing → Inference endpoints: routes inference
- API routing → Model endpoints: routes models
- Identity endpoints → Identity service: handles identity
- Identity service → Identity repository: reads and writes
- Inference endpoints → Runtime manager: requests inference
- Runtime manager → Runtime registry: selects runtime
- Runtime registry → Stub runtime: provides default
- Model endpoints → Model manager: manages models
- Model manager → Model registry: uses registry
- Model manager → Model loaders: loads models
- Model manager → Model repositories: persists metadata
- Configuration → Application entry: configures