artifact-store/docs/adr/0005-v1-tech-stack.md

# ADR-0005 — V1 Technology Stack

Status: accepted
Date: 2026-05-15
Related: ADR-0001, ADR-0002, ADR-0003, ADR-0004

## Context

WP-0001 ("Foundation") cannot start without a pinned stack. The decision
needs to balance:

- ffmpeg / VLC philosophy: minimal dependency budget, sharp boundaries,
  native code at the hot edges, plain tools.
- Python is already implied by `.gitignore` and ecosystem fit (StateHub,
  guide-board, open-cmis-tck are all Python-leaning).
- The data plane will eventually be Rust (ADR-0004); the control plane
  stays in Python and must stay approachable.

## Decision

| Concern | Choice | Rationale |
|---|---|---|
| Language (control plane) | **Python 3.12+** | Async ecosystem, type hints, matches sibling repos. 3.12 specifically: PEP 695 generics, faster CPython, `sys.monitoring`. |
| Package / project manager | **uv** | Single static binary, fast resolver, lockfile-first, replaces `pip + pip-tools + venv + pipx` in one tool. |
| Build backend | **hatchling** (via `pyproject.toml`) | Standards-track PEP 517 backend. No magic. |
| HTTP framework | **FastAPI** (Starlette + Pydantic v2) | OpenAPI generation, async-native, broad community. |
| ASGI server | **uvicorn** (dev), **gunicorn + uvicorn workers** (prod) | Plain, well-understood. |
| Database (prod) | **PostgreSQL 16+** | Source-of-truth event log (ADR-0002) wants `BIGSERIAL`, `BYTEA`, advisory locks, logical replication. |
| Database (dev/embedded) | **SQLite (WAL mode)** | Zero-dependency local. Schema is portable when we use SQLAlchemy Core. |
| DB access | **SQLAlchemy 2.0 Core** + **asyncpg** (prod) / **aiosqlite** (dev) | Core, not ORM — explicit SQL, async drivers. Migrations live below the API surface. |
| Migrations | **Alembic** | Standard, integrates with SQLAlchemy Core, supports both pg and sqlite. |
| Hashing | stdlib **`hashlib`** for SHA-256, **`blake3`** PyPI wheel for BLAKE3 | `blake3` wheel embeds the SIMD-tuned Rust impl with no build-time toolchain. |
| Serialisation | **`cbor2`** for canonical CBOR (ADR-0003); stdlib `json` for JCS or `jcs` PyPI | Smallest deps that satisfy ADR-0003. |
| CLI | **typer** (atop click) | Sits on FastAPI's Pydantic types cleanly; type-driven CLI surface. |
| Tests | **pytest** + **httpx** + **trio-asyncio**-free `pytest-asyncio` | Standard. |
| Lint / format | **ruff** (lint + format) | One tool replaces black + isort + flake8 + pyupgrade. |
| Type checker | **mypy** in `--strict` | Pyright is acceptable for editor support; CI gate is mypy. |
| Logging | stdlib `logging` + `structlog` for structured output | No exotic deps. |
| Metrics / tracing | OpenTelemetry SDK (deferred to its own workplan) | Listed for forward-compatibility; not a v1 dep. |

### Project layout

```
artifact-store/
├── pyproject.toml
├── uv.lock
├── Makefile                              # thin shim: make dev / test / lint / type / migrate
├── alembic.ini
├── src/
│   └── artifactstore/
│       ├── __init__.py
│       ├── identity/                     # content address, digest abstraction (ADR-0001)
│       ├── manifest/                     # canonical CBOR, JCS projection (ADR-0003)
│       ├── events/                       # append-only log + replayer (ADR-0002)
│       ├── retention/                    # policy engine
│       ├── audit/                        # audit emission as event subset
│       ├── storage/                      # adapter SPI + backend registry
│       │   ├── spi.py
│       │   └── backends/
│       │       ├── local.py              # filesystem backend
│       │       └── s3.py                 # placeholder, WP-0004
│       ├── dataplane/                    # SPI + in-process impl (ADR-0004)
│       │   ├── spi.py
│       │   └── inproc.py
│       ├── registry/                     # high-level orchestrator
│       ├── api/
│       │   └── http/                     # FastAPI app
│       ├── cli/                          # typer CLI (thin)
│       └── config.py
├── tests/
│   ├── unit/
│   ├── integration/
│   └── conftest.py
├── migrations/                           # alembic
└── docs/
```

### Commands (T001 acceptance)

```
make dev        # uvicorn with reload, sqlite backend, local FS storage
make test       # pytest -q
make lint       # ruff check + ruff format --check
make type       # mypy --strict src tests
make migrate    # alembic upgrade head
artifactstore   # CLI entry point installed by uv
```

## Consequences

Positive:

- Dependency budget is small and each dep is best-in-class for its slot.
- The same toolchain works on Linux, macOS, and CI without special cases.
- `uv.lock` is checked in; builds are reproducible.
- Every layer maps one-to-one to a docs concept (identity, manifest,
  events, dataplane, etc.), so the codebase remains navigable.

Negative:

- Pydantic v2 is the heaviest non-DB dep; acceptable for the OpenAPI win.
- Choosing SQLAlchemy Core over ORM costs some convenience; we accept
  it because explicit SQL is easier to migrate to Rust later (ADR-0004).
- mypy `--strict` is a per-PR tax; bounded by keeping the codebase small.

## Revision policy

This ADR is the most likely candidate for revision once we have profile
data from real ingestion. Candidates we are already watching:

- Replace `cbor2` with a Rust-backed CBOR codec if profile shows it on
  the hot path.
- Replace `uvicorn` with `granian` (Rust ASGI server) if perf demands.
- Replace `SQLAlchemy Core` with raw `asyncpg` + a tiny query builder
  if Core's abstractions show up in flame graphs.

Each replacement is its own ADR. None of them are v1 work.