loader/_docs/02_document/00_discovery.md

Codebase Discovery

Directory Tree

loader/
├── .cursor/                    # Cursor IDE config and skills
├── .woodpecker/
│   └── build-arm.yml           # Woodpecker CI — ARM64 Docker build
├── .git/
├── Dockerfile                  # Python 3.11-slim, Cython build, Docker CLI
├── README.md
├── requirements.txt            # Python/Cython dependencies
├── setup.py                    # Cython extension build config
├── main.py                     # FastAPI entry point
├── api_client.pyx / .pxd       # Core API client (auth, resource load/upload, CDN)
├── binary_split.py             # Archive decryption + Docker image loading
├── cdn_manager.pyx / .pxd      # S3-compatible CDN upload/download
├── constants.pyx / .pxd        # Shared constants + Loguru logging
├── credentials.pyx / .pxd      # Email/password credential holder
├── hardware_service.pyx / .pxd # OS-specific hardware fingerprint
├── security.pyx / .pxd         # AES-256-CBC encryption/decryption + key derivation
├── unlock_state.py             # Enum for unlock workflow states
├── user.pyx / .pxd             # User model with role enum
└── scripts/                    # (empty)

Tech Stack

Aspect	Technology
Language	Python 3.11 + Cython 3.1.3
Framework	FastAPI + Uvicorn
Build	Cython setup.py build_ext --inplace
Container	Docker (python:3.11-slim), Docker CLI inside container
CI/CD	Woodpecker CI (ARM64 build, pushes to local registry)
CDN/Storage	S3-compatible (boto3)
Auth	JWT (pyjwt, signature unverified decode)
Encryption	AES-256-CBC via cryptography lib
Logging	Loguru (file + stdout/stderr)
HTTP Client	requests
Config	YAML (pyyaml) for CDN config; env vars for URLs/paths

Dependency Graph

Internal Module Dependencies

constants       ← (leaf — no internal deps)
credentials     ← (leaf)
user            ← (leaf)
unlock_state    ← (leaf)
binary_split    ← (leaf — no internal deps, uses requests + cryptography)

security        ← credentials
hardware_service← constants
cdn_manager     ← constants

api_client      ← constants, credentials, cdn_manager, hardware_service, security, user

main            ← unlock_state, api_client (lazy), binary_split (lazy)

Mermaid Diagram

graph TD
    main --> unlock_state
    main -.->|lazy| api_client
    main -.->|lazy| binary_split
    api_client --> constants
    api_client --> credentials
    api_client --> cdn_manager
    api_client --> hardware_service
    api_client --> security
    api_client --> user
    security --> credentials
    hardware_service --> constants
    cdn_manager --> constants

Topological Processing Order

Order	Module	Type	Internal Dependencies
1	constants	Cython	—
2	credentials	Cython	—
3	user	Cython	—
4	unlock_state	Python	—
5	binary_split	Python	—
6	security	Cython	credentials
7	hardware_service	Cython	constants
8	cdn_manager	Cython	constants
9	api_client	Cython	constants, credentials, cdn_manager, hardware_service, security, user
10	main	Python	unlock_state, api_client, binary_split

Entry Points

• main.py — FastAPI application (main:app), served via uvicorn on port 8080

Leaf Modules

• constants, credentials, user, unlock_state, binary_split

External Dependencies

Package	Version	Purpose
fastapi	latest	HTTP API framework
uvicorn	latest	ASGI server
Cython	3.1.3	Compile .pyx → C extensions
requests	2.32.4	HTTP client for API calls
pyjwt	2.10.1	JWT token decoding
cryptography	44.0.2	AES-256-CBC encryption
boto3	1.40.9	S3-compatible CDN operations
loguru	0.7.3	Structured logging
pyyaml	6.0.2	YAML config parsing
psutil	7.0.0	(listed but not used in source)
python-multipart	latest	File upload support for FastAPI

Test Structure

No test files, test directories, or test framework configs found in the workspace.

Existing Documentation

• README.md — one-line description: "Cython/Python service for model download, binary-split decryption, and local cache management."

CI/CD

• Woodpecker CI (.woodpecker/build-arm.yml): triggers on push/manual to dev/stage/main, builds ARM64 Docker image, pushes to localhost:5000/loader:<tag>

Environment Variables

Variable	Default	Used In
RESOURCE_API_URL	https://api.azaion.com	main.py
IMAGES_PATH	/opt/azaion/images.enc	main.py
API_VERSION	latest	main.py