# Azaion.Loader — Documentation Report

## Executive Summary

Azaion.Loader is a Cython/Python microservice that securely distributes encrypted AI model resources and Docker service images to ARM64 edge devices. The codebase consists of 10 modules organized into 4 components, built around a binary-split encryption scheme and hardware-bound key derivation. No test suite exists — creating one is the recommended next step.

## Problem Statement

Edge devices running Azaion's AI/drone services need a self-contained way to authenticate against a central API, download encrypted resources (using a split-storage scheme for security), and bootstrap their Docker environment by decrypting and loading pre-deployed image archives. All security-critical logic must be IP-protected through compiled native extensions.

## Architecture Overview

The system is a single-container FastAPI service that delegates to Cython-compiled modules for encryption, key derivation, and API communication. It uses a binary-split storage model where resources are encrypted and split between an authenticated REST API (small part) and an S3-compatible CDN (large part). Docker image archives are decrypted using a server-provided key fragment and loaded via Docker CLI.

**Technology stack**: Python 3.11 + Cython 3.1.3, FastAPI/Uvicorn, AES-256-CBC (cryptography), boto3 (S3 CDN), Docker CLI

**Deployment**: Single Docker container on ARM64 edge devices, built via Woodpecker CI, pushed to local registry

## Component Summary

| # | Component | Purpose | Dependencies |
|---|-----------|---------|-------------|
| 01 | Core Models | Shared constants, data types (Credentials, User, UnlockState), logging | — |
| 02 | Security | AES-256-CBC encryption, key derivation, hardware fingerprinting | 01 |
| 03 | Resource Management | API client, CDN operations, binary-split resource scheme, Docker unlock | 01, 02 |
| 04 | HTTP API | FastAPI endpoints — thin controller | 01, 03 |

**Implementation order**:
1. Phase 1: Core Models (01) — no dependencies
2. Phase 2: Security (02) — depends on Core Models
3. Phase 3: Resource Management (03) — depends on Core Models + Security
4. Phase 4: HTTP API (04) — depends on Core Models + Resource Management

## System Flows

| Flow | Description | Key Components |
|------|-------------|---------------|
| F1 Authentication | Login → JWT → CDN config init | 04, 03, 02 |
| F2 Resource Download | Small part (API) + big part (CDN/local) → decrypt → return | 04, 03, 02 |
| F3 Resource Upload | Encrypt → split → small to API, big to CDN | 04, 03, 02 |
| F4 Docker Unlock | Auth → key fragment → decrypt archive → docker load | 04, 03 |
| F5 Unlock Status Poll | Read current unlock state | 04 |
| F6 Health/Status | Liveness + readiness probes | 04 |

See `system-flows.md` for full sequence diagrams and flowcharts.

## Risk Summary

| Level | Count | Key Risks |
|-------|-------|-----------|
| High | 2 | No test suite; JWT decoded without signature verification |
| Medium | 4 | No endpoint authorization; shared resource encryption key; synchronous I/O for large files; race condition on ApiClient singleton |
| Low | 3 | Unused dependencies (psutil); dead code declarations; hardcoded log path |

## Test Coverage

No tests exist. Coverage is 0% across all categories.

| Component | Integration | Performance | Security | Acceptance | AC Coverage |
|-----------|-------------|-------------|----------|------------|-------------|
| 01 Core Models | 0 | 0 | 0 | 0 | 0/18 |
| 02 Security | 0 | 0 | 0 | 0 | 0/18 |
| 03 Resource Mgmt | 0 | 0 | 0 | 0 | 0/18 |
| 04 HTTP API | 0 | 0 | 0 | 0 | 0/18 |

**Overall acceptance criteria coverage**: 0 / 18 (0%)

## Key Decisions (Inferred from Code)

| # | Decision | Rationale | Alternatives Rejected |
|---|----------|-----------|----------------------|
| 1 | Cython for IP protection | Prevent reverse-engineering of security logic | Pure Python (too readable), Rust (ecosystem mismatch) |
| 2 | Binary-split resource storage | Security: compromise of one storage is insufficient | Single encrypted download (bandwidth cost), unencrypted CDN (security risk) |
| 3 | Docker CLI via subprocess | Simplicity for Docker-in-Docker on edge devices | Docker Python SDK (extra dependency), external image loading (not self-contained) |
| 4 | Hardware-bound key derivation | Tie resource access to specific physical machines | Software-only licensing (easily transferable), hardware dongles (extra hardware) |

## Open Questions

| # | Question | Impact | Assigned To |
|---|----------|--------|-------------|
| 1 | Should JWT signature verification be enabled? | Security — currently trusts API server blindly | Team |
| 2 | Is `psutil` needed or can it be removed from requirements? | Cleanup — unused dependency | Team |
| 3 | Should endpoint-level authorization be enforced? | Security — currently all endpoints accessible post-login | Team |
| 4 | Should the resource encryption key be per-user instead of shared? | Security — currently all users share one key for big/small split | Team |
| 5 | What are the target latency/throughput requirements? | Performance — no SLAs defined | Product |

## Artifact Index

| File | Description |
|------|-------------|
| `_docs/00_problem/problem.md` | Problem statement |
| `_docs/00_problem/restrictions.md` | Hardware, software, environment restrictions |
| `_docs/00_problem/acceptance_criteria.md` | 18 acceptance criteria |
| `_docs/00_problem/input_data/data_parameters.md` | Data schemas and sources |
| `_docs/00_problem/security_approach.md` | Security architecture |
| `_docs/01_solution/solution.md` | Solution overview |
| `_docs/02_document/00_discovery.md` | Codebase discovery |
| `_docs/02_document/modules/*.md` | 10 module-level docs |
| `_docs/02_document/components/01_core_models/description.md` | Core Models component spec |
| `_docs/02_document/components/02_security/description.md` | Security component spec |
| `_docs/02_document/components/03_resource_management/description.md` | Resource Management component spec |
| `_docs/02_document/components/04_http_api/description.md` | HTTP API component spec |
| `_docs/02_document/architecture.md` | System architecture |
| `_docs/02_document/system-flows.md` | System flow diagrams |
| `_docs/02_document/data_model.md` | Entity data model |
| `_docs/02_document/deployment/containerization.md` | Docker containerization |
| `_docs/02_document/deployment/ci_cd_pipeline.md` | Woodpecker CI pipeline |
| `_docs/02_document/deployment/observability.md` | Logging and health checks |
| `_docs/02_document/diagrams/components.md` | Component relationship diagram |
| `_docs/02_document/04_verification_log.md` | Verification pass results |
| `_docs/02_document/FINAL_report.md` | This report |