OmniRoute/src/lib/db/AGENTS.md

# src/lib/db/ — SQLite Persistence Layer

**Purpose**: Domain-driven SQLite persistence. Each module owns a specific table set. Schema migrations are versioned and idempotent. No raw SQL in routes — all ops go through `src/lib/db/` modules.

Live count: `ls src/lib/db/*.ts | wc -l` (currently 117). Migrations: `ls src/lib/db/migrations/*.sql | wc -l` (currently 148).

---

## Core Infrastructure

- **`core.ts`** — `getDbInstance()` returns singleton `better-sqlite3` with WAL journaling. Exports `rowToCamel()` (snake_case → camelCase), `encryptConnectionFields()` for provider credentials at rest. `SCHEMA_SQL` defines **17 base tables** (verify: `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for `_omniroute_migrations`).
- **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Each migration is idempotent.
- **`db/migrations/`** — 148 SQL files (`001_initial_schema.sql` → `153_radar_local_model_state.sql`; numbering has intentional gaps). Each runs in a transaction, never fails partially.
- **`localDb.ts`** — Re-export layer only. Never add logic here.

## Key Domain Modules

| Module                 | Tables / Scope            | Responsibility                                      |
| ---------------------- | ------------------------- | --------------------------------------------------- |
| `providers.ts`         | `provider_connections`    | OAuth/API key provider registration and credentials |
| `models.ts`            | `models`                  | Model definitions, capabilities, pricing            |
| `combos.ts`            | `combos`, `combo_targets` | Combo routing configs, target ordering              |
| `apiKeys.ts`           | `api_keys`                | API key lifecycle, scopes, quota tracking           |
| `settings.ts`          | `settings`                | KV store for system configuration                   |
| `secrets.ts`           | `secrets`                 | Encrypted secret storage (API keys at rest)         |
| `quotaSnapshots.ts`    | `quota_snapshots`         | Historical quota usage for analytics                |
| `quotaPools.ts`        | `quota_pools`             | Quota-Share pool management                         |
| `creditBalance.ts`     | `credit_balance`          | Per-provider credit tracking                        |
| `compression.ts`       | compression settings      | Prompt compression pipeline config                  |
| `compressionCombos.ts` | `compression_combos`      | Per-combo compression pipeline assignments          |
| `evals.ts`             | eval tables               | Eval framework persistence                          |
| `webhooks.ts`          | `webhooks`                | Event-driven webhook subscriptions and logs         |
| `reasoningCache.ts`    | reasoning cache           | Hybrid in-memory + SQLite reasoning replay          |
| `skills.ts`            | `skills`                  | Skill registration and metadata                     |
| `plugins.ts`           | `plugins`                 | Plugin marketplace state                            |
| `gamification.ts`      | gamification tables       | Levels, badges, leaderboard                         |
| `notion.ts`            | notion tables             | Notion integration state                            |
| `obsidian.ts`          | obsidian tables           | Obsidian vault integration state                    |
| `files.ts`             | file storage              | Uploaded file management                            |
| `batches.ts`           | batch processing          | Batch job tracking                                  |
| `featureFlags.ts`      | feature flags             | Runtime feature flag overrides                      |
| `backup.ts`            | backup ops                | Serialize/deserialize entire DB state               |
| `cleanup.ts`           | cleanup ops               | Stale data purging                                  |
| `healthCheck.ts`       | health ops                | DB health monitoring                                |
| `databaseSettings.ts`  | database settings         | DB-level configuration                              |

Full list: `ls src/lib/db/*.ts | wc -l` (115 files). Drift detection: `npm run check:docs-counts`.

## Encryption & Security

- **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using AES-256-GCM
- **`encryptConnectionFields()`** in `core.ts` — automatic encryption when storing provider credentials
- **`secrets.ts`** — dedicated encrypted store for long-term secret handling
- **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs

## Adding a New Domain Module

1. Create `src/lib/db/[module].ts` with CRUD functions
2. Export from `src/lib/localDb.ts` (add re-export)
3. If new tables: create migration in `db/migrations/NNN_[description].sql`
4. Migration runs automatically at startup via `migrationRunner.ts`
5. Add unit tests in `tests/unit/db/`

## Anti-Patterns

- Raw SQL in routes — always use domain module functions
- Direct `prepare()` statements outside `db/` — breaks modularity
- Adding logic to `localDb.ts` — re-export layer only
- Barrel-importing from `localDb.ts` — import specific modules instead
- Skipping migrations for schema changes — all changes go through `db/migrations/`