---
summary: The moving parts and how a request flows through them.
title: Architecture
path: concepts/architecture
status: published
---

# Architecture

ScaiAtlas is a FastAPI service backed by a metadata database, an object store, and a
cache, fronted by four client surfaces and integrated with ScaiLabs identity and
routing.

```
        ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐
        │ REST API │  │  Web UI  │  │   CLI    │  │ P2P Tracker│
        └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬─────┘
             └─────────────┴─────────────┴──────────────┘
                                 │
                     ┌───────────┴───────────┐
                     │      Service layer     │
                     │  Namespace · Model ·   │
                     │  Version · Variant     │
                     └───────────┬───────────┘
                                 │
        ┌────────────────┬───────┴────────┬────────────────┐
        ▼                ▼                ▼                ▼
   ┌─────────┐      ┌─────────┐      ┌─────────┐     ┌──────────┐
   │ MariaDB │      │  S3 /   │      │  Redis  │     │  ScaiKey │
   │(metadata)│     │ filesys │      │ (cache) │     │  (auth)  │
   └─────────┘      └─────────┘      └─────────┘     └──────────┘
```

## The pieces

- **API server** — FastAPI app. All model-management routes live under `/api/v1`. Interactive OpenAPI docs are served at `/docs` (Swagger) and `/redoc` when debug mode is on.
- **Metadata database** — namespaces, models, versions, variants, files, members, API keys, access logs. The source of truth for structure and permissions.
- **Object storage** — the actual model bytes. Two backends: **S3-compatible** (default) and a **filesystem** backend for single-node deployments. Clients never talk to storage directly — transfers are proxied or signed by the API.
- **Redis** — rate limiting and caching.
- **ScaiKey** — the ScaiLabs identity provider. Issues the JWTs and validates the tokens behind OAuth and device-flow logins. See [Authentication](/docs/scaiatlas/concepts/authentication).
- **P2P tracker** — optional. Tracks which peers hold which version chunks so clusters can seed among themselves. See [Storage & distribution](/docs/scaiatlas/concepts/storage-and-distribution).

## How a download flows

1. Client calls `GET …/versions/{version}/download` with a bearer token.
2. The API checks namespace **VIEW/DOWNLOAD** permission for the caller.
3. The API returns file metadata (paths, sizes, checksums, URLs), or streams bytes directly through `…/download/files/{path}` with HTTP range support.
4. The client writes files and verifies each `checksum_sha256`.

Because transfer is API-mediated, storage credentials never leave the server, and
the same permission model covers both metadata and bytes.

## Where ScaiAtlas sits in ScaiLabs

- **ScaiKey** provides identity (users, groups, tenants, tokens).
- **ScaiGrid** handles inference routing; it pulls models from ScaiAtlas.
- **P2P distribution** lets inference clusters share model bytes without repeatedly hitting origin storage.

## Deployment shapes

ScaiAtlas ships as a container and runs standalone (single or multi-node), under
Docker Compose, or on Kubernetes. Storage backend, database URL, Redis, and ScaiKey
client credentials are all configured via `SCAIATLAS_*` environment variables.
Deployment and configuration are covered in the operations docs, not here.