| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 5 | 0% |
| Commands | 0 | 1 | 6 | 0% |
| Section tags | 2 | 2 | 4 | 25% |
What each file covers
Sections
0 shared · 6 only in A · 5 only in B- − src/lib/db/ — SQLite Persistence Layer
- − Core Infrastructure
- − Key Domain Modules
- − Encryption & Security
- − Adding a New Domain Module
- − Anti-Patterns
- + Security and Cleanliness Rules for AI Assistants
- + 1. File Placement & Organization
- + 2. Hard Rules (mirror of `CLAUDE.md`)
- + 3. Codebase navigation
- + 4. Local development access
Commands
0 shared · 1 only in A · 6 only in B- − npm run check:docs-counts
- + vitest.config.ts
- + eslint.config.mjs
- + playwright.config.ts
- + prettier.config.mjs
- + docker-compose*.yml
- + npm run test:coverage
Section tags
2 shared · 2 only in A · 4 only in B- − code-style
- − database
- + test
- + lint-format
- + do-not
- + agent-behaviour
- architecture
- security
Line diff
diegosouzapw/OmniRoute · src/lib/db/AGENTS.md
@@ −1 @@
1# src/lib/db/ — SQLite Persistence Layer
2
3**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.
4
5Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Migrations: `ls src/lib/db/migrations/*.sql | wc -l` (currently 110).
6
7---
8
9## Core Infrastructure
10
11- **`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`).
12- **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Each migration is idempotent.
13- **`db/migrations/`** — 110 SQL files (`001_initial_schema.sql` → `110_*.sql`). Each runs in a transaction, never fails partially.
14- **`localDb.ts`** — Re-export layer only. Never add logic here.
15
16## Key Domain Modules
17
18| Module | Tables / Scope | Responsibility |
19| ---------------------- | ------------------------- | --------------------------------------------------- |
20| `providers.ts` | `provider_connections` | OAuth/API key provider registration and credentials |
21| `models.ts` | `models` | Model definitions, capabilities, pricing |
22| `combos.ts` | `combos`, `combo_targets` | Combo routing configs, target ordering |
23| `apiKeys.ts` | `api_keys` | API key lifecycle, scopes, quota tracking |
24| `settings.ts` | `settings` | KV store for system configuration |
25| `secrets.ts` | `secrets` | Encrypted secret storage (API keys at rest) |
26| `quotaSnapshots.ts` | `quota_snapshots` | Historical quota usage for analytics |
27| `quotaPools.ts` | `quota_pools` | Quota-Share pool management |
28| `creditBalance.ts` | `credit_balance` | Per-provider credit tracking |
29| `compression.ts` | compression settings | Prompt compression pipeline config |
30| `compressionCombos.ts` | `compression_combos` | Per-combo compression pipeline assignments |
31| `evals.ts` | eval tables | Eval framework persistence |
32| `webhooks.ts` | `webhooks` | Event-driven webhook subscriptions and logs |
33| `reasoningCache.ts` | reasoning cache | Hybrid in-memory + SQLite reasoning replay |
34| `skills.ts` | `skills` | Skill registration and metadata |
35| `plugins.ts` | `plugins` | Plugin marketplace state |
36| `gamification.ts` | gamification tables | Levels, badges, leaderboard |
37| `notion.ts` | notion tables | Notion integration state |
38| `obsidian.ts` | obsidian tables | Obsidian vault integration state |
39| `files.ts` | file storage | Uploaded file management |
40| `batches.ts` | batch processing | Batch job tracking |
41| `featureFlags.ts` | feature flags | Runtime feature flag overrides |
42| `backup.ts` | backup ops | Serialize/deserialize entire DB state |
43| `cleanup.ts` | cleanup ops | Stale data purging |
44| `healthCheck.ts` | health ops | DB health monitoring |
45| `databaseSettings.ts` | database settings | DB-level configuration |
46
47Full list: `ls src/lib/db/*.ts | wc -l` (95 files). Drift detection: `npm run check:docs-counts`.
48
49## Encryption & Security
50
51- **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using AES-256-GCM
52- **`encryptConnectionFields()`** in `core.ts` — automatic encryption when storing provider credentials
53- **`secrets.ts`** — dedicated encrypted store for long-term secret handling
54- **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs
55
56## Adding a New Domain Module
57
581. Create `src/lib/db/[module].ts` with CRUD functions
592. Export from `src/lib/localDb.ts` (add re-export)
603. If new tables: create migration in `db/migrations/NNN_[description].sql`
614. Migration runs automatically at startup via `migrationRunner.ts`
625. Add unit tests in `tests/unit/db/`
63
64## Anti-Patterns
65
66- Raw SQL in routes — always use domain module functions
67- Direct `prepare()` statements outside `db/` — breaks modularity
68- Adding logic to `localDb.ts` — re-export layer only
69- Barrel-importing from `localDb.ts` — import specific modules instead
70- Skipping migrations for schema changes — all changes go through `db/migrations/`
71
diegosouzapw/OmniRoute · GEMINI.md
@@ +1 @@
1# Security and Cleanliness Rules for AI Assistants
2
3> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`.
4
5## 1. File Placement & Organization
6
7- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
8- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder.
9
10**The Project Root MUST ONLY CONTAIN:**
11
12- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`)
13- Dependency files (`package.json`, `package-lock.json`)
14- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`)
15- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`)
16
17When creating _any_ validation tests or one-off logic scripts, default to using `scripts/ad-hoc/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
18
19## 2. Hard Rules (mirror of `CLAUDE.md`)
20
211. **Never commit secrets or credentials.** Use `.env` (auto-generated from `.env.example`) or a vault. Passwords, OAuth secrets, API keys, and Cookie values must never appear in committed files.
222. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only.
233. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this.
244. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches.
255. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules.
266. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly.
277. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
288. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`.
299. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`).
3010. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it.
31
32## 3. Codebase navigation
33
34| Task | Read this first |
35| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` |
37| Architecture overview | `docs/architecture/ARCHITECTURE.md` |
38| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
39| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |
40| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` |
41| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |
42
43## 4. Local development access
44
45The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific:
46
47- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login).
48- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo.
49
50> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.
51
@@ −1 +1 @@
1−# src/lib/db/ — SQLite Persistence Layer
1+# Security and Cleanliness Rules for AI Assistants
22
3−**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.
3+> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`.
44
5−Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Migrations: `ls src/lib/db/migrations/*.sql | wc -l` (currently 110).
5+## 1. File Placement & Organization
66
7−---
7+- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
8+- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder.
89
9−## Core Infrastructure
10+**The Project Root MUST ONLY CONTAIN:**
1011
11−- **`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`).
12−- **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Each migration is idempotent.
13−- **`db/migrations/`** — 110 SQL files (`001_initial_schema.sql` → `110_*.sql`). Each runs in a transaction, never fails partially.
14−- **`localDb.ts`** — Re-export layer only. Never add logic here.
12+- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`)
13+- Dependency files (`package.json`, `package-lock.json`)
14+- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`)
15+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`)
1516
16−## Key Domain Modules
17+When creating _any_ validation tests or one-off logic scripts, default to using `scripts/ad-hoc/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
1718
18−| Module | Tables / Scope | Responsibility |
19−| ---------------------- | ------------------------- | --------------------------------------------------- |
20−| `providers.ts` | `provider_connections` | OAuth/API key provider registration and credentials |
21−| `models.ts` | `models` | Model definitions, capabilities, pricing |
22−| `combos.ts` | `combos`, `combo_targets` | Combo routing configs, target ordering |
23−| `apiKeys.ts` | `api_keys` | API key lifecycle, scopes, quota tracking |
24−| `settings.ts` | `settings` | KV store for system configuration |
25−| `secrets.ts` | `secrets` | Encrypted secret storage (API keys at rest) |
26−| `quotaSnapshots.ts` | `quota_snapshots` | Historical quota usage for analytics |
27−| `quotaPools.ts` | `quota_pools` | Quota-Share pool management |
28−| `creditBalance.ts` | `credit_balance` | Per-provider credit tracking |
29−| `compression.ts` | compression settings | Prompt compression pipeline config |
30−| `compressionCombos.ts` | `compression_combos` | Per-combo compression pipeline assignments |
31−| `evals.ts` | eval tables | Eval framework persistence |
32−| `webhooks.ts` | `webhooks` | Event-driven webhook subscriptions and logs |
33−| `reasoningCache.ts` | reasoning cache | Hybrid in-memory + SQLite reasoning replay |
34−| `skills.ts` | `skills` | Skill registration and metadata |
35−| `plugins.ts` | `plugins` | Plugin marketplace state |
36−| `gamification.ts` | gamification tables | Levels, badges, leaderboard |
37−| `notion.ts` | notion tables | Notion integration state |
38−| `obsidian.ts` | obsidian tables | Obsidian vault integration state |
39−| `files.ts` | file storage | Uploaded file management |
40−| `batches.ts` | batch processing | Batch job tracking |
41−| `featureFlags.ts` | feature flags | Runtime feature flag overrides |
42−| `backup.ts` | backup ops | Serialize/deserialize entire DB state |
43−| `cleanup.ts` | cleanup ops | Stale data purging |
44−| `healthCheck.ts` | health ops | DB health monitoring |
45−| `databaseSettings.ts` | database settings | DB-level configuration |
19+## 2. Hard Rules (mirror of `CLAUDE.md`)
4620
47−Full list: `ls src/lib/db/*.ts | wc -l` (95 files). Drift detection: `npm run check:docs-counts`.
21+1. **Never commit secrets or credentials.** Use `.env` (auto-generated from `.env.example`) or a vault. Passwords, OAuth secrets, API keys, and Cookie values must never appear in committed files.
22+2. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only.
23+3. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this.
24+4. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches.
25+5. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules.
26+6. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly.
27+7. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
28+8. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`.
29+9. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`).
30+10. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it.
4831
49−## Encryption & Security
32+## 3. Codebase navigation
5033
51−- **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using AES-256-GCM
52−- **`encryptConnectionFields()`** in `core.ts` — automatic encryption when storing provider credentials
53−- **`secrets.ts`** — dedicated encrypted store for long-term secret handling
54−- **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs
34+| Task | Read this first |
35+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36+| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` |
37+| Architecture overview | `docs/architecture/ARCHITECTURE.md` |
38+| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
39+| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |
40+| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` |
41+| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |
5542
56−## Adding a New Domain Module
43+## 4. Local development access
5744
58−1. Create `src/lib/db/[module].ts` with CRUD functions
59−2. Export from `src/lib/localDb.ts` (add re-export)
60−3. If new tables: create migration in `db/migrations/NNN_[description].sql`
61−4. Migration runs automatically at startup via `migrationRunner.ts`
62−5. Add unit tests in `tests/unit/db/`
45+The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific:
6346
64−## Anti-Patterns
47+- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login).
48+- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo.
6549
66−- Raw SQL in routes — always use domain module functions
67−- Direct `prepare()` statements outside `db/` — breaks modularity
68−- Adding logic to `localDb.ts` — re-export layer only
69−- Barrel-importing from `localDb.ts` — import specific modules instead
70−- Skipping migrations for schema changes — all changes go through `db/migrations/`
50+> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.
7151
