vibed/quotesdb/docs/api/ARCHITECTURE.md

quotesdb API — Architecture

Overview

Single Axum router binary (src/bin/api/main.rs) that serves a quotes REST API. Targets both:

• Native (host): Axum + Tokio + rusqlite — for local dev and integration tests
• wasm32-unknown-unknown: workers-rs + Cloudflare D1 — for production Cloudflare Workers

Component structure

src/bin/api/
├── main.rs              # Entry point — opens DB, wires router, starts server (native only)
├── db/
│   ├── mod.rs           # QuoteRepository trait + ListResult/DeleteResult/DbError types
│   ├── migrations.rs    # SQL DDL strings (CREATE TABLE IF NOT EXISTS)
│   ├── native.rs        # NativeRepository: tokio-rusqlite implementation
│   ├── connection.rs    # open() helper — opens SQLite with WAL and FK pragma
│   └── d1.rs            # D1Repository: workers-rs stub (wasm32 only)
└── handlers/
    └── mod.rs           # All 7 route handlers + router() factory function

DB layer

The QuoteRepository trait abstracts over two backends:

Target	Implementation	Storage
Native (not(wasm32))	NativeRepository	Local SQLite via tokio-rusqlite
wasm32	D1Repository	Cloudflare D1 via workers-rs

On native targets, the trait uses async_trait (Send-capable futures), allowing Arc<dyn QuoteRepository> to be used as Axum state.

On wasm32, the trait uses async_trait(?Send) because D1Database wraps JS values that aren't Send.

Request flow (native)

TCP :3000 → Axum router → handler fn
                              ↓
                    State<Arc<dyn QuoteRepository>>
                              ↓
                    NativeRepository.method()
                              ↓
                    tokio-rusqlite → SQLite file

Auth model

No user accounts. Each quote has an auth_code (4-word passphrase from EFF word list), generated at creation time and returned once in the creation response. Stored plaintext in quotes.auth_code.

For update and delete, the caller supplies the auth code in the X-Auth-Code request header. A mismatch returns 403 Forbidden.

OpenAPI spec

api/openapi.yaml is the source of truth. build.rs converts it to JSON at compile time, writing to $OUT_DIR/openapi.json. The GET /api/ handler serves it via include_str!.

Router ordering

GET /api/quotes/random is registered before GET /api/quotes/:id to prevent "random" being matched as an ID.