> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model

> Understand the two SQLite databases and the pipeline migration ladder.

The product uses two SQLite databases with separate owners.

## Database boundary

| Database                               | Owner               | Main contents                                                                                                         |
| -------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| <code>apps/web/data/app.sqlite3</code> | Next.js application | Jobs, workspace metadata, credentials, chat, page evaluations, AgentMail state, team, credits, and API keys           |
| <code>data/db/geo.sqlite3</code>       | Python pipeline     | Runs, prompts, responses, citations, signals, research artifacts, scores, audits, reports, and recommendation history |

The application opens the pipeline database in read-only query mode for product reads. Python CLI code owns its writes and schema migrations.

<Warning>
  Do not point both database roles at one file or let application code write directly to pipeline tables. Their lifecycle and migration contracts differ.
</Warning>

## 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.

| Version | Added contract                                                                                                                                |
| ------: | --------------------------------------------------------------------------------------------------------------------------------------------- |
|      v1 | Runs, prompts, responses, citations, extractions, mentions, metrics, and recommendations                                                      |
|      v2 | <code>reddit\_thread</code> recommendation type                                                                                               |
|      v3 | Canonical recommendation lifecycle, state versions, transitions, drafts, reviews, and legacy compatibility view                               |
|      v4 | Research runs, signals, and immutable artifacts                                                                                               |
|      v5 | Prompt lineage, provider attempts, and prompt rejections                                                                                      |
|      v6 | SEO scores and insights, technical audits and checks, generation keys, report catalog and snapshots, and rebuilt immutable v2 draft contracts |

## 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:

<Steps>
  <Step title="Stop new launches">
    Stop new job launches.
  </Step>

  <Step title="Let operations settle">
    Let active operations settle or record their recovery state.
  </Step>

  <Step title="Copy the databases and artifacts">
    Copy both database files and referenced artifacts.
  </Step>

  <Step title="Restore as a matched set">
    Restore them as a matched set.
  </Step>

  <Step title="Run migrations before accepting writes">
    Run the normal pipeline migration entrypoint before accepting writes.
  </Step>
</Steps>

Do not manually increment the pipeline schema version.