# ADR-0004: SQLite as the primary datastore

**Status:** Accepted (2026-08-08)

## Context

The design doc specified no storage backend for the canonical rules document, permissions, audit
log, sessions, secret metadata, or the approval queue. Options considered were SQLite, a bundled
Postgres, and git-backed YAML in a Gitea repository with a database for everything else.

The git-backed option was genuinely attractive in a Gitea shop — free versioning, diffs, and
PR-based review of guardrail changes. It was rejected because Web Panel edits and direct git edits
create two write paths to the same canonical data that must then be reconciled.

## Decision

**SQLite**, one file (`bridle.db`), holding `projects`, `agents`, `tokens`, `permissions`,
`audit_log`, `rules_documents` (JSON plus `schema_version`), `guardrails` with provenance, and
`approval_queue`.

## Consequences

- Zero operational overhead; backup is copying one file.
- Correct default for the single-host, single-user target.
- Rules versioning must be built explicitly (document history in-table) rather than inherited from
  git.
- Migration to Postgres remains straightforward if multi-host or a multi-user panel ever
  materializes. Keep SQL portable and avoid SQLite-specific constructs where a standard equivalent
  exists.