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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

        ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐
        │ 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.
• P2P tracker — optional. Tracks which peers hold which version chunks so clusters can seed among themselves. See Storage & 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.