# 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

```mermaid
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    |