System overview
How the SDK, dashboard, Rust API, ClickHouse, and artifact storage fit together.
InstantML has four moving parts: SDKs write training-loop events, a Rust API validates and stores them, ClickHouse holds operational records and metric history, and the dashboard reads those records back for run comparison.
Primary product path
| Producer | API boundary | Storage path |
|---|---|---|
| Python SDK / uploader | Rust API | ClickHouse operational records |
| Dashboard (Next.js) | Rust API | ClickHouse metric tables |
| SDK and dashboard artifact flows | Rust API | Artifact byte storage |
The Rust API is the single backend boundary. It owns the route contract for SDK ingestion, dashboard reads, imports, exports, usage, billing gates, and artifact metadata. Neither the browser nor the SDK ever talks to ClickHouse or object storage directly.
Component responsibilities
| Component | Responsibility |
|---|---|
| Python SDK | Create runs, log metrics, console logs, attributes, artifacts, rich objects, checkpoints, and source context. |
| Uploader | Drain process-isolated spool events from disk and replay them through the API. |
| Rust API | Validate requests, enforce auth/scopes/limits, store records, stream artifact downloads, and expose dashboard/API routes. |
| Control-plane Postgres | Store account records: users, organizations, memberships, sessions, API keys, billing, invitations, tenant routes, dashboard preferences, and saved workspace views. Single-binary local mode keeps these records in ClickHouse instead. |
| ClickHouse operational layer | Store low-volume append-only product records (projects, runs, attributes, artifacts, reports, imports). |
| ClickHouse metric layer | Store raw scalar and per-rank metric points and maintained metric summaries. |
| Artifact store | Store artifact bytes in private object storage (hosted) or on local disk (self-hosted single binary). |
| Dashboard and docs (Next.js) | Browse, chart, compare, annotate, export, administer workspaces, and serve this documentation. |
Hosted topology
The hosted API is one public HTTPS URL backed by two service roles.
| Layer | Role |
|---|---|
| Browser / dashboard and Python SDK / uploader | Send all product traffic to the public HTTPS API. |
| Public HTTPS API | Routes each request to the control or data service. |
| Control service | Reads and writes the control-plane Postgres database for account, billing, and tenant-route records. |
| Data service | Reads and writes tenant ClickHouse databases and private artifact buckets. |
The control service handles auth, workspaces, sessions, API keys, billing, seats, invitations, tenant-route metadata, dashboard preferences, and saved workspace views. The data service handles projects, runs, metrics, console logs, attributes, rich objects, artifacts, reports, imports, export, and usage. Tenant run data and metrics live in InstantML-owned ClickHouse on Google Cloud; see Service planes for the full route split.
Design constraints you can rely on
- List endpoints are bounded; no endpoint returns unbounded history.
- Raw metric history is fetched through dedicated series endpoints with explicit limits.
- Metric summaries are maintained during ingestion, so run tables never scan full metric history.
- Artifact byte uploads and downloads are separate paths from scalar metric ingestion.
- Every API key resolves to exactly one workspace, with an optional project scope.
- Exports are explicit, bounded, and report truncation.