loader/_docs/02_document/architecture.md

Azaion.Loader — Architecture

1. System Context

Problem being solved: Azaion's suite of AI/drone services ships as encrypted Docker images. Edge devices need a secure way to authenticate, download encryption keys, decrypt the image archive, and load it into Docker — plus an ongoing mechanism to download and upload encrypted model resources (split into small+big parts for security and CDN offloading).

System boundaries:

• Inside: FastAPI service handling auth, resource management, and Docker image unlock
• Outside: Azaion Resource API, S3-compatible CDN, Docker daemon, external HTTP clients

External systems:

System	Integration Type	Direction	Purpose
Azaion Resource API	REST (HTTPS)	Both	Authentication, resource download/upload, key fragment retrieval
S3-compatible CDN	S3 API (boto3)	Both	Large resource part storage
Docker daemon	CLI (subprocess)	Outbound	Load decrypted image archives, inspect images
Host OS	CLI (subprocess)	Inbound	Hardware fingerprint collection

2. Technology Stack

Layer	Technology	Version	Rationale
Language	Python + Cython	3.11 / 3.1.3	Cython for IP protection (compiled .so) + performance
Framework	FastAPI + Uvicorn	latest	Async HTTP, auto-generated OpenAPI docs
Database	None	—	Stateless service; all persistence is external
Cache	In-memory (module globals)	—	JWT token, hardware fingerprint, CDN config
Message Queue	None	—	Synchronous request-response only
Container	Docker (python:3.11-slim)	—	Docker CLI installed inside container for docker load
CI/CD	Woodpecker CI	—	ARM64 Docker builds pushed to local registry

Key constraints:

• Must run on ARM64 edge devices
• Requires Docker-in-Docker (Docker socket mount) for image loading
• Cython compilation at build time — .pyx files compiled to native extensions for IP protection

3. Deployment Model

Environments: Development (local), Production (edge devices)

Infrastructure:

• Containerized via Docker (single container)
• Runs on edge devices with Docker socket access
• No orchestration layer — standalone container

Environment-specific configuration:

Config	Development	Production
RESOURCE_API_URL	https://api.azaion.com	https://api.azaion.com (same)
IMAGES_PATH	/opt/azaion/images.enc	/opt/azaion/images.enc
Secrets	Env vars / cdn.yaml	Env vars / cdn.yaml (encrypted)
Logging	stdout + stderr	File (Logs/) + stdout + stderr
Docker socket	Mounted from host	Mounted from host

4. Data Model Overview

Core entities:

Entity	Description	Owned By Component
Credentials	Email + password pair	01 Core Models
User	Authenticated user with role	01 Core Models
RoleEnum	Authorization role hierarchy	01 Core Models
UnlockState	State machine for unlock workflow	01 Core Models
CDNCredentials	S3 endpoint + read/write key pairs	03 Resource Mgmt

Key relationships:

• Credentials → User: login produces a User from JWT claims
• Credentials → CDNCredentials: credentials enable downloading the encrypted cdn.yaml config

Data flow summary:

• Client → Loader → Resource API: authentication, encrypted resource download (small part)
• Client → Loader → CDN: large resource part upload/download
• Client → Loader → Docker: decrypted image archive loading

5. Integration Points

Internal Communication

From	To	Protocol	Pattern
HTTP API (04)	Resource Mgmt (03)	Direct call	Request-Response
Resource Mgmt	Security (02)	Direct call	Request-Response
Resource Mgmt	Core Models (01)	Direct call	Read constants

External Integrations

External System	Protocol	Auth	Rate Limits	Failure Mode
Azaion Resource API	REST/HTTPS	JWT Bearer	Unknown	Retry once on 401/403; raise on 500/409
S3-compatible CDN	S3 API/HTTPS	Access key pair	Unknown	Return False, log error
Docker daemon	CLI/socket	Docker socket	—	Raise CalledProcessError

6. Non-Functional Requirements

Requirement	Target	Measurement	Priority
Availability	Service uptime	/health endpoint	High
Latency (p95)	Varies by resource size	Per-request timing	Medium
Data retention	30 days (logs)	Loguru rotation config	Low

No explicit SLAs, throughput targets, or recovery objectives are defined in the codebase.

7. Security Architecture

Authentication: JWT Bearer tokens issued by Azaion Resource API. Tokens decoded without signature verification (trusts the API server).

Authorization: Role-based (RoleEnum: NONE → Operator → Validator → CompanionPC → Admin → ResourceUploader → ApiAdmin). Roles parsed from JWT but not enforced by Loader endpoints.

Data protection:

• At rest: AES-256-CBC encrypted resources on disk; Docker images stored as encrypted .enc archive
• In transit: HTTPS for API calls; S3 HTTPS for CDN
• Secrets management: CDN credentials stored in encrypted cdn.yaml downloaded from API; user credentials in memory only

Key derivation:

• Per-user/per-machine keys: SHA-384(email + password + hardware_hash + salt) → used for API resource downloads
• Shared resource key: SHA-384(fixed_salt) → used for big/small resource split encryption
• Hardware binding: SHA-384("Azaion_" + hardware_fingerprint + salt) → ties decryption to specific hardware

Audit logging: Application-level logging via Loguru (file + stdout/stderr). No structured audit trail.

8. Key Architectural Decisions

ADR-001: Cython for IP Protection

Context: The loader handles encryption keys and security-sensitive logic that should not be trivially readable.

Decision: Core modules (api_client, security, cdn_manager, hardware_service, credentials, user, constants) are written in Cython and compiled to native .so extensions.

Alternatives considered:

1. Pure Python with obfuscation — rejected because obfuscation is reversible
2. Compiled language (Rust/Go) — rejected because of tighter integration needed with Python ecosystem (FastAPI, boto3)

Consequences: Build step required (setup.py build_ext --inplace); cdef methods not callable from pure Python; debugging compiled extensions is harder.

ADR-002: Binary-Split Resource Scheme

Context: Large model files need secure distribution. Storing entire encrypted files on one server creates a single point of compromise.

Decision: Resources are encrypted, then split into a small part (uploaded to the authenticated API) and a large part (uploaded to CDN). Decryption requires both parts.

Alternatives considered:

1. Single encrypted download from API — rejected because of bandwidth/cost for large files
2. Unencrypted CDN with signed URLs — rejected because CDN compromise would expose models

Consequences: More complex download/upload logic; local caching of big parts for performance; CDN credentials managed separately from API credentials.

ADR-003: Docker-in-Docker for Image Loading

Context: The loader needs to inject Docker images into the host Docker daemon on edge devices.

Decision: Mount Docker socket into the loader container; use Docker CLI (docker load, docker image inspect) via subprocess.

Alternatives considered:

1. Docker API via Python library — rejected because Docker CLI is simpler and universally available
2. Image loading outside the loader — rejected because the unlock workflow needs to be self-contained

Consequences: Container requires Docker socket mount (security implication); Docker CLI must be installed in the container image.