Skip to main content
The product uses two SQLite databases with separate owners.

​
Database boundary

The application opens the pipeline database in read-only query mode for product reads. Python CLI code owns its writes and schema migrations.
Do not point both database roles at one file or let application code write directly to pipeline tables. Their lifecycle and migration contracts differ.

​
Pipeline schema ladder

The current pipeline schema version is 6. A fresh database is created directly at version 6. Existing databases move through ordered migrations that preserve prior data.

​
Append-only records

Several tables use append-only history:
  • Credit ledger and cost events in the application database
  • Recommendation transitions, drafts, and reviews
  • Provider attempts after a response is recorded
  • Frozen score and report snapshots
Corrections create a new record or explicit adjustment instead of editing evidence in place.

​
Cross-database identifiers

Workspace slugs, run IDs, job IDs, and operation IDs connect records across the boundary. They do not replace authorization checks. A web job can fail while a pipeline run is partial, and an operation can settle independently of the user-facing job state.

​
Backup and recovery

Back up both files and the report and worker artifact directories. For a consistent recovery:
1

Stop new launches

Stop new job launches.
2

Let operations settle

Let active operations settle or record their recovery state.
3

Copy the databases and artifacts

Copy both database files and referenced artifacts.
4

Restore as a matched set

Restore them as a matched set.
5

Run migrations before accepting writes

Run the normal pipeline migration entrypoint before accepting writes.
Do not manually increment the pipeline schema version.