# alilotfi23/lxd-management-api architecture

> Architecture diagram of the GitHub repository alilotfi23/lxd-management-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alilotfi23/lxd-management-api
- Repository: https://github.com/alilotfi23/lxd-management-api

## Overview

1. This repository is a FastAPI-based management API that sits between API clients and an LXD server. The API itself is stateless for LXD control-plane calls, but it keeps local user/auth data in a database and proxies nearly all infrastructure actions to LXD over its REST API.

2. The top-level request path is: external client → FastAPI app → API router/middleware → auth/RBAC checks and request-scoped deps → resource route handler → service layer → LXD REST API. Most endpoints are versioned under `/api/v1`; `/health` is intentionally unversioned for deployment probing.

3. `app/main.py` is the application composition root. It wires middleware, CORS, global exception handling, request IDs/logging behavior, and startup/shutdown lifecycle. It also creates the FastAPI app and mounts the versioned router aggregator from `app/api/v1/api.py`.

4. The API layer is split by resource under `app/api/v1/routes/`: auth, instances, snapshots, backups, storage, networks, projects, images, operations, and system. These route modules are thin controllers; they validate input/output with Pydantic schemas, enforce authorization, and delegate the actual work to services.

5. Authentication and authorization are handled separately from LXD auth. `app/core/security.py` implements local user auth with JWT access/refresh tokens and password hashing, while `app/api/deps.py` provides bearer-token extraction and role checks. The role model is hierarchical (`viewer` < `operator` < `admin`), so higher roles inherit lower-role permissions.

6. Local user identity is persisted in the database layer under `app/db/`. This appears to be the only durable application state besides Alembic migrations: SQLAlchemy async models, async session management, CRUD helpers, and first-run seeding. The README indicates SQLite is the default datastore, used for users and token-related subjects, not for LXD resources themselves.

7. The infrastructure-control boundary is `app/services/lxd_client.py`. It is the repo’s adapter over the raw LXD REST API using `httpx`, and it supports two transport modes: local Unix socket access or remote HTTPS with mutual TLS. This is the main external dependency boundary, and it is where requests to LXD are formed and responses/errors are normalized.

8. Long-running LXD work is modeled explicitly in `app/services/lxd_operations.py` and the operations routes. Since LXD often returns `202 Accepted` plus an operation reference for create/copy/snapshot/migrate actions, the API returns operation metadata immediately and exposes poll, wait, cancel, and WebSocket event-stream endpoints for follow-up observation.

9. The schemas in `app/schemas/` define the API contract for each resource family: auth, instances, networks, storage, projects, snapshots, images, and shared LXD structures. These Pydantic v2 models are the boundary between HTTP payloads and service calls, and they keep request validation/response shaping separate from infrastructure code.

10. Cross-cutting utilities live in `app/core/` and `app/utils/`. `config.py` centralizes environment-driven settings, `limiter.py` rate-limits sensitive endpoints like auth, `logging.py` provides structured JSON logging, and `pagination.py` applies response pagination on top of LXD list results. These are support subsystems rather than business logic.

11. The API exposes a mix of synchronous CRUD endpoints and LXD-native operational endpoints. Examples include instance lifecycle actions, exec/console over WebSocket, image copy/import, storage attach/detach, network lease/state queries, and project-scoped listing via `?project=`. The design keeps LXD semantics visible instead of hiding them behind a separate domain model.

12. Database schema changes are managed with Alembic in `alembic/` and an initial migration for the users table. This indicates the local database is expected to evolve independently of LXD, but still remains small and focused on application authentication state.

13. Testing is isolated from real infrastructure. `tests/` uses pytest with an in-memory SQLite database and a mocked LXD client, so the test boundary validates route/auth/service behavior without requiring a live LXD daemon. That separation is important for the architecture diagram: LXD is an external system, not a test fixture dependency.

14. Deployment is container-oriented. `Dockerfile`, `docker-compose.yml`, and the Makefile show the app is intended to run as a service container with environment-based configuration, optionally mounting the host LXD socket or TLS credentials depending on connection mode. The `.env.example` file is the primary runtime configuration contract.

Main entry points: [`app/api/v1/api.py`](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/api.py) (API v1), [`app/services/lxd_client.py`](https://github.com/alilotfi23/lxd-management-api/blob/main/app/services/lxd_client.py) (LXD client), [`app/main.py`](https://github.com/alilotfi23/lxd-management-api/blob/main/app/main.py) (App entry), [`app/api/v1/routes/instances.py`](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/instances.py) (Instance routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App runtime"]
  node_node_main["App entry<br/>FastAPI composition<br/>[main.py]"]
  node_node_api_v1["API v1<br/>router aggregator<br/>[api.py]"]
  node_node_deps["API deps<br/>authz helpers<br/>[deps.py]"]
  node_node_auth_route["Auth routes<br/>controller<br/>[auth.py]"]
  node_node_instance_route["Instance routes<br/>controller<br/>[instances.py]"]
  node_node_snapshot_route["Snapshot routes<br/>controller<br/>[snapshots.py]"]
  node_node_backup_route["Backup routes<br/>controller<br/>[backups.py]"]
  node_node_network_route["Network routes<br/>controller<br/>[networks.py]"]
  node_node_storage_route["Storage routes<br/>controller<br/>[storage.py]"]
  node_node_project_route["Project routes<br/>controller<br/>[projects.py]"]
  node_node_image_route["Image routes<br/>controller<br/>[images.py]"]
  node_node_operation_route["Operation routes<br/>controller<br/>[operations.py]"]
  node_node_system_route["System routes<br/>controller<br/>[system.py]"]
  node_node_security["Security<br/>jwt auth<br/>[security.py]"]
  node_node_config["Config<br/>settings<br/>[config.py]"]
  node_node_limiter["Rate limit<br/>middleware support<br/>[limiter.py]"]
  node_node_lxd_ops["Ops model<br/>operation service<br/>[lxd_operations.py]"]
  node_node_pagination["Pagination<br/>response helper<br/>[pagination.py]"]
  node_node_logging["Logging<br/>structured logs<br/>[logging.py]"]
  node_node_app_schema["API schemas<br/>pydantic contracts<br/>[__init__.py]"]
end

subgraph group_group_data["Persistence"]
  node_node_db_models["DB models<br/>sqlalchemy models<br/>[models.py]"]
  node_node_db_session["DB session<br/>async session<br/>[session.py]"]
  node_node_db_crud["DB CRUD<br/>persistence helpers<br/>[crud.py]"]
  node_node_migration["Migrations<br/>alembic"]
end

subgraph group_group_platform["Platform"]
  node_node_lxd_client["LXD client<br/>REST adapter<br/>[lxd_client.py]"]
  node_node_lxd_external[("LXD server<br/>external system")]
  node_node_local_db[("Local DB<br/>sqlite store")]
  node_node_client(("API clients<br/>external clients"))
end

subgraph group_group_test["Tests"]
  node_node_tests["Tests<br/>pytest suite<br/>[conftest.py]"]
end

node_node_client -->|"HTTP requests"| node_node_main
node_node_main -->|"mounts"| node_node_api_v1
node_node_main -->|"loads settings"| node_node_config
node_node_main -->|"configures logs"| node_node_logging
node_node_main -->|"installs"| node_node_limiter
node_node_api_v1 -->|"routes"| node_node_auth_route
node_node_api_v1 -->|"routes"| node_node_instance_route
node_node_api_v1 -->|"routes"| node_node_snapshot_route
node_node_api_v1 -->|"routes"| node_node_backup_route
node_node_api_v1 -->|"routes"| node_node_network_route
node_node_api_v1 -->|"routes"| node_node_storage_route
node_node_api_v1 -->|"routes"| node_node_project_route
node_node_api_v1 -->|"routes"| node_node_image_route
node_node_api_v1 -->|"routes"| node_node_operation_route
node_node_api_v1 -->|"routes"| node_node_system_route
node_node_auth_route -->|"auth checks"| node_node_deps
node_node_instance_route -->|"auth checks"| node_node_deps
node_node_auth_route -->|"uses"| node_node_security
node_node_security -->|"reads users"| node_node_db_crud
node_node_db_crud -->|"sessions"| node_node_db_session
node_node_db_crud -->|"maps models"| node_node_db_models
node_node_db_session -->|"connects to"| node_node_local_db
node_node_db_models -->|"persists to"| node_node_local_db
node_node_db_models -->|"evolved by"| node_node_migration
node_node_instance_route -->|"validates payloads"| node_node_app_schema
node_node_snapshot_route -->|"validates payloads"| node_node_app_schema
node_node_image_route -->|"validates payloads"| node_node_app_schema
node_node_instance_route -->|"proxies to"| node_node_lxd_client
node_node_snapshot_route -->|"proxies to"| node_node_lxd_client
node_node_backup_route -->|"proxies to"| node_node_lxd_client
node_node_network_route -->|"proxies to"| node_node_lxd_client
node_node_storage_route -->|"proxies to"| node_node_lxd_client
node_node_project_route -->|"proxies to"| node_node_lxd_client
node_node_image_route -->|"proxies to"| node_node_lxd_client
node_node_operation_route -->|"tracks"| node_node_lxd_ops
node_node_lxd_ops -->|"polls via"| node_node_lxd_client
node_node_lxd_client -->|"REST API"| node_node_lxd_external
node_node_operation_route -->|"ws/events"| node_node_lxd_external
node_node_system_route -->|"status"| node_node_lxd_client
node_node_instance_route -->|"lists"| node_node_pagination
node_node_network_route -->|"lists"| node_node_pagination
node_node_main -.->|"validated by"| node_node_tests
node_node_tests -.->|"in-memory SQLite"| node_node_local_db
node_node_tests -.->|"mocked"| node_node_lxd_client

click node_node_main "https://github.com/alilotfi23/lxd-management-api/blob/main/app/main.py"
click node_node_api_v1 "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/api.py"
click node_node_deps "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/deps.py"
click node_node_auth_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/auth.py"
click node_node_instance_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/instances.py"
click node_node_snapshot_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/snapshots.py"
click node_node_backup_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/backups.py"
click node_node_network_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/networks.py"
click node_node_storage_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/storage.py"
click node_node_project_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/projects.py"
click node_node_image_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/images.py"
click node_node_operation_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/operations.py"
click node_node_system_route "https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/system.py"
click node_node_security "https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/security.py"
click node_node_config "https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/config.py"
click node_node_limiter "https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/limiter.py"
click node_node_db_models "https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/models.py"
click node_node_db_session "https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/session.py"
click node_node_db_crud "https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/crud.py"
click node_node_migration "https://github.com/alilotfi23/lxd-management-api/blob/main/alembic/versions/0001_create_users_table.py"
click node_node_lxd_client "https://github.com/alilotfi23/lxd-management-api/blob/main/app/services/lxd_client.py"
click node_node_lxd_ops "https://github.com/alilotfi23/lxd-management-api/blob/main/app/services/lxd_operations.py"
click node_node_pagination "https://github.com/alilotfi23/lxd-management-api/blob/main/app/utils/pagination.py"
click node_node_logging "https://github.com/alilotfi23/lxd-management-api/blob/main/app/utils/logging.py"
click node_node_app_schema "https://github.com/alilotfi23/lxd-management-api/blob/main/app/schemas/__init__.py"
click node_node_tests "https://github.com/alilotfi23/lxd-management-api/blob/main/tests/conftest.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_api_v1,node_node_deps,node_node_auth_route,node_node_instance_route,node_node_snapshot_route,node_node_backup_route,node_node_network_route,node_node_storage_route,node_node_project_route,node_node_image_route,node_node_operation_route,node_node_system_route,node_node_security,node_node_config,node_node_limiter,node_node_lxd_ops,node_node_pagination,node_node_logging,node_node_app_schema toneBlue
class node_node_db_models,node_node_db_session,node_node_db_crud,node_node_migration toneAmber
class node_node_lxd_client,node_node_lxd_external,node_node_local_db,node_node_client toneMint
class node_node_tests toneRose
```

## Components

### App runtime

FastAPI application, API routing, auth, services, and schemas

- [App entry](https://github.com/alilotfi23/lxd-management-api/blob/main/app/main.py): FastAPI composition · Creates the FastAPI app, wires middleware, exception handling, logging, lifecycle hooks, and mounts the versioned API. · `app/main.py`
- [API v1](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/api.py): router aggregator · Versioned router assembly for the public API surface under /api/v1. · `app/api/v1/api.py`
- [API deps](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/deps.py): authz helpers · Bearer token extraction and role-check dependencies used by routes. · `app/api/deps.py`
- [Auth routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/auth.py): controller · Login, refresh, and user/auth endpoints. · `app/api/v1/routes/auth.py`
- [Instance routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/instances.py): controller · Instance lifecycle and exec/console-style operations. · `app/api/v1/routes/instances.py`
- [Snapshot routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/snapshots.py): controller · Snapshot CRUD and snapshot-triggered operations. · `app/api/v1/routes/snapshots.py`
- [Backup routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/backups.py): controller · Backup lifecycle endpoints that proxy LXD backup actions. · `app/api/v1/routes/backups.py`
- [Network routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/networks.py): controller · Network listing and state/lease management endpoints. · `app/api/v1/routes/networks.py`
- [Storage routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/storage.py): controller · Storage pool and attachment/detachment endpoints. · `app/api/v1/routes/storage.py`
- [Project routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/projects.py): controller · Project-scoped listing and project management endpoints. · `app/api/v1/routes/projects.py`
- [Image routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/images.py): controller · Image import, copy, and image metadata endpoints. · `app/api/v1/routes/images.py`
- [Operation routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/operations.py): controller · Poll, wait, cancel, and event-stream endpoints for asynchronous LXD operations. · `app/api/v1/routes/operations.py`
- [System routes](https://github.com/alilotfi23/lxd-management-api/blob/main/app/api/v1/routes/system.py): controller · System and health endpoints, including unversioned deployment probing. · `app/api/v1/routes/system.py`
- [Security](https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/security.py): jwt auth · Local user auth, password hashing, access/refresh JWT handling, and role model logic. · `app/core/security.py`
- [Config](https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/config.py): settings · Environment-driven application and connection settings. · `app/core/config.py`
- [Rate limit](https://github.com/alilotfi23/lxd-management-api/blob/main/app/core/limiter.py): middleware support · Rate-limits sensitive endpoints such as authentication. · `app/core/limiter.py`
- [Ops model](https://github.com/alilotfi23/lxd-management-api/blob/main/app/services/lxd_operations.py): operation service · Models and coordinates LXD long-running operations and their metadata lifecycle. · `app/services/lxd_operations.py`
- [Pagination](https://github.com/alilotfi23/lxd-management-api/blob/main/app/utils/pagination.py): response helper · Applies pagination over LXD list responses. · `app/utils/pagination.py`
- [Logging](https://github.com/alilotfi23/lxd-management-api/blob/main/app/utils/logging.py): structured logs · Structured JSON logging utilities and request log behavior. · `app/utils/logging.py`
- [API schemas](https://github.com/alilotfi23/lxd-management-api/blob/main/app/schemas/__init__.py): pydantic contracts · Shared request/response models for auth, instances, networks, storage, projects, snapshots, images, and LXD structures. · `app/schemas/__init__.py`

### Persistence

Local database layer and migration management

- [DB models](https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/models.py): sqlalchemy models · Persistent user and token-related subject models. · `app/db/models.py`
- [DB session](https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/session.py): async session · Async SQLAlchemy session management. · `app/db/session.py`
- [DB CRUD](https://github.com/alilotfi23/lxd-management-api/blob/main/app/db/crud.py): persistence helpers · Database access helpers for local user/auth state. · `app/db/crud.py`
- [Migrations](https://github.com/alilotfi23/lxd-management-api/blob/main/alembic/versions/0001_create_users_table.py): alembic · Database schema evolution, including the initial users table migration. · `alembic/versions/0001_create_users_table.py`

### Platform

Deployment, runtime configuration, and external systems

- [LXD client](https://github.com/alilotfi23/lxd-management-api/blob/main/app/services/lxd_client.py): REST adapter · HTTPX-based adapter over the LXD REST API with local socket or remote mTLS transport. · `app/services/lxd_client.py`
- **LXD server**: external system · External LXD daemon reached through the REST API.
- **Local DB**: sqlite store · Durable local application state for users and auth-related records.
- **API clients**: external clients · Consumers calling the management API.

### Tests

Isolated tests with mocked infrastructure

- [Tests](https://github.com/alilotfi23/lxd-management-api/blob/main/tests/conftest.py): pytest suite · Isolated tests using in-memory SQLite and a mocked LXD client. · `tests/conftest.py`

## Connections

- API clients → App entry: HTTP requests · External clients call the API entrypoint.
- App entry → API v1: mounts · The application wires the versioned router aggregator.
- App entry → Config: loads settings · Runtime configuration is injected at startup.
- App entry → Logging: configures logs · Startup sets request and structured logging behavior.
- App entry → Rate limit: installs · Cross-cutting rate limiting is attached to the app.
- API v1 → Auth routes: routes · Versioned API exposes auth endpoints.
- API v1 → Instance routes: routes · Versioned API exposes instance endpoints.
- API v1 → Snapshot routes: routes · Versioned API exposes snapshot endpoints.
- API v1 → Backup routes: routes · Versioned API exposes backup endpoints.
- API v1 → Network routes: routes · Versioned API exposes network endpoints.
- API v1 → Storage routes: routes · Versioned API exposes storage endpoints.
- API v1 → Project routes: routes · Versioned API exposes project endpoints.
- API v1 → Image routes: routes · Versioned API exposes image endpoints.
- API v1 → Operation routes: routes · Versioned API exposes operation follow-up endpoints.
- API v1 → System routes: routes · Versioned API exposes system and health endpoints.
- Auth routes → API deps: auth checks · Route handlers enforce bearer auth and role checks.
- Instance routes → API deps: auth checks · Instance actions are gated by dependency checks.
- Auth routes → Security: uses · Auth handlers rely on local JWT and password logic.
- Security → DB CRUD: reads users · Local auth reads and writes database-backed user state.
- DB CRUD → DB session: sessions · CRUD helpers run through async sessions.
- DB CRUD → DB models: maps models · Database helpers operate on SQLAlchemy models.
- DB session → Local DB: connects to · Async sessions persist state in the local database.
- DB models → Local DB: persists to · Application state is stored in the local database.
- DB models → Migrations: evolved by · Schema changes are managed independently by Alembic.
- Instance routes → API schemas: validates payloads · Routes use Pydantic contracts for request and response shaping.
- Snapshot routes → API schemas: validates payloads · Snapshot endpoints use shared schemas.
- Image routes → API schemas: validates payloads · Image endpoints use shared schemas.
- Instance routes → LXD client: proxies to · Resource actions are delegated to the LXD adapter.
- Snapshot routes → LXD client: proxies to · Snapshot operations are delegated to the LXD adapter.
- Backup routes → LXD client: proxies to · Backup operations are delegated to the LXD adapter.
- Network routes → LXD client: proxies to · Network queries and updates are delegated to the LXD adapter.
- Storage routes → LXD client: proxies to · Storage operations are delegated to the LXD adapter.
- Project routes → LXD client: proxies to · Project operations are delegated to the LXD adapter.
- Image routes → LXD client: proxies to · Image actions are delegated to the LXD adapter.
- Operation routes → Ops model: tracks · Operation endpoints manage asynchronous operation metadata.
- Ops model → LXD client: polls via · Operations are checked and controlled through the LXD adapter.
- LXD client → LXD server: REST API · The adapter talks to the external LXD daemon.
- Operation routes → LXD server: ws/events · Long-running work is exposed as poll/wait/cancel/event streams.
- System routes → LXD client: status · System endpoints query infrastructure state through the adapter.
- Instance routes → Pagination: lists · List endpoints paginate LXD results.
- Network routes → Pagination: lists · Network listing is paginated when applicable.
- App entry → Tests: validated by · The app structure is exercised by the test suite.
- Tests → Local DB: in-memory SQLite · Tests use an isolated local database.
- Tests → LXD client: mocked · Tests replace the real LXD client with a mock.
