# Asobi architecture
Asobi has a versioned, backend-neutral API above a concrete storage backend. The current backend is Turso; PostgreSQL and RocksDB remain design targets, not supported runtime backends.
```text
CLI / document workflows
|
api::v1
GraphStore SearchStore DocumentStore MaintenanceStore SnapshotStore
|
backend::turso::TursoBackend
|
Turso schema, native FTS, vector32, WAL/retry, and SQL
```
## API boundary
`src/api/v1.rs` contains only domain requests, results, capabilities, snapshots, and stable errors. It does not import Turso, SQL, rows, pragmas, or connection handles. The CLI receives a `TursoBackend` at startup and calls the capability traits; a future backend can satisfy the same contract without changing the domain-facing operations.
The API contract is versioned independently from the storage schema. Optional features are reported through `BackendCapabilities`, and unsupported operations return `ApiError::Unsupported` rather than silently doing nothing.
## Turso backend
All Turso-specific code lives under `src/backend/turso/`:
- `db.rs` — graph schema, CRUD, search, and migrations;
- `constant.rs` — Turso-owned SQL and schema statements;
- `vector.rs` — optional `vector32` storage and exact cosine search;
- `tx.rs` — multi-process WAL startup and immediate-transaction retries.
Graph keyword search uses Turso native `USING fts` indexes with `fts_match` and `fts_score`. It does not use SQLite FTS5 virtual tables, external-content triggers, porter stemming, or `bm25()`.
The document tier stores embeddings with `vector32` and searches with `vector_distance_cos` over the chunks table. This is exact/brute-force search, which is appropriate for the current project-document scale; no `libsql_vector_idx` or ANN index is assumed.
Turso's experimental multi-process WAL is enabled at open. Database opening and `BEGIN IMMEDIATE` writes retry transient lock contention with bounded backoff. Legacy journal-mode and busy-timeout environment overrides are not supported.
## Database initialization
v0.5 initializes `data/asobi.turso.db` with the current schema, native FTS indexes, and optional vector tables. A future file-backed backend should use a backend-qualified filename of its own; remote backends do not need a local DB file. If an old `asobi.db` is present while the Turso file is absent, startup warns and still creates a fresh Turso database.
## Verification
The backend contract test checks that `TursoBackend` implements `api::v1::Backend` and reports its capabilities. The real CLI checks are split into:
- `scripts/verify_cli.py` — backend-neutral graph behavior;
- `scripts/verify_cli.turso.py` — Turso backend identity/capabilities and native keyword search;
- `scripts/verify_documents_cli.py` — optional document workflow.
The first alternate backend should add its own backend-specific verifier while reusing the API contract tests and backend-neutral CLI checks.