# Azaion.Loader — Solution

## 1. Product Solution Description

Azaion.Loader is a lightweight HTTP microservice that runs on edge devices to manage the secure distribution of encrypted Docker images and AI model resources. It acts as a bridge between the centralized Azaion Resource API, an S3-compatible CDN, and the local Docker daemon.

```mermaid
graph LR
    Client([HTTP Client]) --> Loader[Azaion.Loader<br/>FastAPI]
    Loader --> API[Azaion Resource API]
    Loader --> CDN[S3 CDN]
    Loader --> Docker[Docker Daemon]
    Loader --> FS[Local Filesystem]
```

The service provides three core capabilities:
1. **Authentication** — proxy login to the Azaion Resource API, extracting user roles from JWT
2. **Resource management** — encrypted download/upload of AI models using a binary-split scheme (small part via API, large part via CDN)
3. **Docker unlock** — download a key fragment, decrypt an encrypted Docker image archive, and load it into the local Docker daemon

## 2. Architecture

### Solution Table

| Solution | Tools | Advantages | Limitations | Requirements | Security | Cost | Fit |
|----------|-------|-----------|-------------|-------------|----------|------|-----|
| Cython + FastAPI microservice | Python 3.11, Cython 3.1.3, FastAPI, boto3, cryptography | IP protection via compiled extensions; fast HTTP; Python ecosystem access | Single-threaded blocking I/O for large files; Cython debugging difficulty | ARM64 edge device, Docker socket access | AES-256-CBC encryption, hardware-bound keys, split-storage scheme | Minimal — single container, no database | High — purpose-built for edge deployment with security constraints |

### Component Architecture

| # | Component | Modules | Responsibility |
|---|-----------|---------|----------------|
| 01 | Core Models | constants, credentials, user, unlock_state | Shared types, constants, logging |
| 02 | Security | security, hardware_service | AES-256-CBC crypto, key derivation, HW fingerprint |
| 03 | Resource Management | api_client, cdn_manager, binary_split | Auth, resource download/upload, Docker unlock |
| 04 | HTTP API | main | FastAPI endpoints (thin controller) |

### Key Design Patterns

- **Binary-split storage**: Resources are encrypted then split — small part on authenticated API, large part on CDN. Compromise of either alone is insufficient.
- **Hardware-bound keys**: Download encryption keys derive from user credentials + machine hardware fingerprint (CPU, GPU, RAM, drive serial).
- **Compiled extensions**: Security-sensitive Cython modules compile to `.so` files, protecting IP and key derivation logic.
- **Lazy initialization**: `ApiClient` and Cython imports are lazy-loaded to minimize startup time and avoid import-time side effects.

## 3. Testing Strategy

**Current state**: No test suite exists. No test framework is configured. No test files are present in the codebase.

**Integration points that would benefit from testing**:
- API authentication flow (login → JWT decode → User creation)
- Binary-split encrypt/decrypt round-trip
- CDN upload/download operations
- Hardware fingerprint collection (platform-specific)
- Docker image unlock state machine

## 4. References

| Artifact | Path | Description |
|----------|------|-------------|
| Dockerfile | `Dockerfile` | Container build with Cython compilation + Docker CLI |
| CI config | `.woodpecker/build-arm.yml` | ARM64 Docker build pipeline |
| Dependencies | `requirements.txt` | Python/Cython package list |
| Build config | `setup.py` | Cython extension compilation |
| Architecture doc | `_docs/02_document/architecture.md` | Full architecture document |
| System flows | `_docs/02_document/system-flows.md` | All system flow diagrams |