# negativexq/ml-platform-infrastructure architecture

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

- Interactive diagram: https://gitdiagram.com/negativexq/ml-platform-infrastructure
- Repository: https://github.com/negativexq/ml-platform-infrastructure

## Overview

ML Platform is a self-hosted Kubernetes platform for training and serving models, LLMs, and user functions. Its main workflow runs from project-scoped management in the web UI and control API, through persisted desired state and reconciliation, to training or deployment on external systems; callers use a separate gateway for inference. The graph preserves documented access, model, rollout, monitoring, and UI capabilities. Some subsystem links are based on README architecture descriptions because their implementation files were not sampled.

Main entry points: [`controlplane/api/app.py`](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/api/app.py) (Control API), [`controlplane/reconciliation`](https://github.com/negativexq/ml-platform-infrastructure/tree/main/controlplane/reconciliation) (Reconcilers), [`controlplane/gateway/app.py`](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/gateway/app.py) (Inference gateway), [`controlplane/ui/web/src/router.tsx`](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/ui/web/src/router.tsx) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webui["Web UI<br/>[router.tsx]"]
end

subgraph group_management["Control plane"]
  node_control_api["Control API<br/>[app.py]"]
  node_identity["Identity and access<br/>[identity.py]"]
  node_projects["Projects and jobs<br/>[projects.py]"]
  node_pipelines["Pipeline definitions<br/>[pipelines.py]"]
  node_pipeline_runs["Pipeline runs<br/>[pipeline_runs.py]"]
  node_models["Models and versions<br/>[models.py]"]
  node_deployments["Deployments and rollouts<br/>[deployments.py]"]
  node_api_keys["Gateway access<br/>[api_access.py]"]
  node_domain["Domain state<br/>[entities.py]"]
end

subgraph group_execution["Lifecycle execution"]
  node_persistence["SQL persistence<br/>[sql.py]"]
  node_reconcilers["Reconcilers"]
end

subgraph group_integrations["Platform integrations"]
  node_workflow["Workflow adapter<br/>[argo.py]"]
  node_cluster["Kubernetes provisioner<br/>[provisioner.py]"]
  node_registry["MLflow tracking<br/>[tracking.py]"]
  node_serving_adapter["KServe adapter<br/>[kserve.py]"]
end

subgraph group_runtime["Serving and observability"]
  node_gateway["Inference gateway<br/>[app.py]"]
  node_inference["Model inference<br/>[inference.py]"]
  node_monitoring["Monitoring<br/>[metrics.py]"]
end

node_people(("People"))
node_postgres[("PostgreSQL")]
node_callers(("API callers"))
node_external_systems["Serving endpoints"]
node_observability_stack["Telemetry and dashboards"]

node_people -->|"use"| node_webui
node_webui -->|"calls"| node_control_api
node_control_api -->|"authenticates"| node_identity
node_control_api -->|"routes requests"| node_projects
node_control_api -->|"routes requests"| node_pipelines
node_control_api -->|"routes requests"| node_pipeline_runs
node_control_api -->|"manages"| node_models
node_control_api -->|"manages"| node_deployments
node_control_api -->|"manages"| node_api_keys
node_projects -->|"uses entities"| node_domain
node_pipelines -->|"creates definitions"| node_domain
node_control_api -->|"writes intent"| node_persistence
node_persistence -->|"stores state"| node_postgres
node_reconcilers -->|"read desired state"| node_postgres
node_reconcilers -->|"provisions projects"| node_cluster
node_reconcilers -->|"executes pipelines"| node_workflow
node_reconcilers -->|"syncs model registry"| node_registry
node_reconcilers -->|"reconciles serving"| node_serving_adapter
node_callers -->|"send inference requests"| node_gateway
node_gateway -->|"checks keys"| node_api_keys
node_gateway -->|"routes inference"| node_external_systems
node_serving_adapter -->|"manages endpoints"| node_external_systems
node_monitoring -->|"exports telemetry"| node_observability_stack
node_pipeline_runs -.->|"tracks execution"| node_workflow
node_inference -.->|"serves predictions"| node_external_systems

click node_webui "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/ui/web/src/router.tsx"
click node_control_api "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/api/app.py"
click node_identity "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/identity.py"
click node_projects "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/projects.py"
click node_pipelines "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/pipelines.py"
click node_pipeline_runs "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/pipeline_runs.py"
click node_models "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/models.py"
click node_deployments "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/deployments.py"
click node_api_keys "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/api_access.py"
click node_domain "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/domain/entities.py"
click node_persistence "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/persistence/sql.py"
click node_reconcilers "https://github.com/negativexq/ml-platform-infrastructure/tree/main/controlplane/reconciliation"
click node_workflow "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/workflow/argo.py"
click node_cluster "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/kubernetes/provisioner.py"
click node_registry "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/mlflow/tracking.py"
click node_serving_adapter "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/serving/kserve.py"
click node_gateway "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/gateway/app.py"
click node_inference "https://github.com/negativexq/ml-platform-infrastructure/blob/main/app/inference.py"
click node_monitoring "https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/observability/metrics.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_webui toneBlue
class node_control_api,node_identity,node_projects,node_pipelines,node_pipeline_runs,node_models,node_deployments,node_api_keys,node_domain,node_postgres toneAmber
class node_persistence,node_reconcilers,node_callers toneMint
class node_workflow,node_cluster,node_registry,node_serving_adapter toneRose
class node_gateway,node_inference,node_monitoring,node_people,node_external_systems,node_observability_stack toneIndigo
```

## Components

### User experience

- [Web UI](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/ui/web/src/router.tsx): `controlplane/ui/web/src/router.tsx`

### Control plane

- [Control API](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/api/app.py): `controlplane/api/app.py`
- [Identity and access](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/identity.py): `controlplane/application/identity.py`
- [Projects and jobs](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/projects.py): `controlplane/application/projects.py`
- [Pipeline definitions](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/pipelines.py): `controlplane/application/pipelines.py`
- [Pipeline runs](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/pipeline_runs.py): `controlplane/application/pipeline_runs.py`
- [Models and versions](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/models.py): `controlplane/application/models.py`
- [Deployments and rollouts](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/deployments.py): `controlplane/application/deployments.py`
- [Gateway access](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/application/api_access.py): `controlplane/application/api_access.py`
- [Domain state](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/domain/entities.py): `controlplane/domain/entities.py`

### Lifecycle execution

- [SQL persistence](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/persistence/sql.py): `controlplane/persistence/sql.py`
- [Reconcilers](https://github.com/negativexq/ml-platform-infrastructure/tree/main/controlplane/reconciliation): `controlplane/reconciliation`

### Platform integrations

- [Workflow adapter](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/workflow/argo.py): `controlplane/adapters/workflow/argo.py`
- [Kubernetes provisioner](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/kubernetes/provisioner.py): `controlplane/adapters/kubernetes/provisioner.py`
- [MLflow tracking](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/mlflow/tracking.py): `controlplane/adapters/mlflow/tracking.py`
- [KServe adapter](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/adapters/serving/kserve.py): `controlplane/adapters/serving/kserve.py`

### Serving and observability

- [Inference gateway](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/gateway/app.py): `controlplane/gateway/app.py`
- [Model inference](https://github.com/negativexq/ml-platform-infrastructure/blob/main/app/inference.py): `app/inference.py`
- [Monitoring](https://github.com/negativexq/ml-platform-infrastructure/blob/main/controlplane/observability/metrics.py): `controlplane/observability/metrics.py`

### Other components

- **People**
- **PostgreSQL**
- **API callers**
- **Serving endpoints**
- **Telemetry and dashboards**

## Connections

- People → Web UI: use
- Web UI → Control API: calls
- Control API → Identity and access: authenticates (evidence: `controlplane/api/app.py`)
- Control API → Projects and jobs: routes requests (evidence: `controlplane/api/app.py`)
- Control API → Pipeline definitions: routes requests (evidence: `controlplane/api/app.py`)
- Control API → Pipeline runs: routes requests (evidence: `controlplane/api/app.py`)
- Control API → Models and versions: manages (evidence: `controlplane/api/app.py`)
- Control API → Deployments and rollouts: manages (evidence: `controlplane/api/app.py`)
- Control API → Gateway access: manages (evidence: `controlplane/api/app.py`)
- Projects and jobs → Domain state: uses entities (evidence: `controlplane/application/projects.py`)
- Pipeline definitions → Domain state: creates definitions (evidence: `controlplane/application/pipelines.py`)
- Control API → SQL persistence: writes intent
- SQL persistence → PostgreSQL: stores state
- Reconcilers → PostgreSQL: read desired state
- Reconcilers → Kubernetes provisioner: provisions projects
- Reconcilers → Workflow adapter: executes pipelines
- Reconcilers → MLflow tracking: syncs model registry
- Reconcilers → KServe adapter: reconciles serving
- API callers → Inference gateway: send inference requests
- Inference gateway → Gateway access: checks keys
- Inference gateway → Serving endpoints: routes inference
- KServe adapter → Serving endpoints: manages endpoints
- Monitoring → Telemetry and dashboards: exports telemetry
- Pipeline runs → Workflow adapter: tracks execution
- Model inference → Serving endpoints: serves predictions
