loader/_docs/01_solution/solution.md

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.

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