focus-flow/Codex Documentation/Archived plans/V1_ADR_002_SQLite_Document_Schema_V1.md

V1 ADR 002: SQLite Document Schema V1

Status: Accepted
Date: 2026-06-26

Context

The project pivoted from MongoDB to SQLite‑first persistence.
We need a stable, versioned relational schema that maps cleanly to the domain objects while staying behind the repository abstraction. Drift will manage migrations.

Decision

• Database file: adhd_scheduler.sqlite in the user data directory.
• Schema version: 1 (managed by Drift).
• Tables

Table	Purpose	Key fields
tasks	Authoritative task rows	id TEXT PRIMARY KEY, owner_id TEXT, project_id, parent_id, type, status, priority, reward, difficulty, scheduled_start_utc, scheduled_end_utc, actual_start_utc, actual_end_utc, completed_at_utc, revision INT, created_at_utc, updated_at_utc, backlog_entered_at_utc, backlog_entered_provenance TEXT
projects	Project configuration	id TEXT PRIMARY KEY, owner_id, name, color_key, config defaults …, archived_at_utc, revision
locked_blocks	Recurring / one‑off locked time	id TEXT PRIMARY KEY, owner_id, name, date TEXT, start_time TEXT, end_time TEXT, recurrence_json, hidden_by_default INT, archived_at_utc, revision
locked_overrides	Date‑scoped overrides	id TEXT PRIMARY KEY, owner_id, locked_block_id, date TEXT, type, JSON fields
settings	One row per owner	owner_id TEXT PRIMARY KEY, timezone_id, day_start_minutes, day_end_minutes, compact_mode INT, revision
activities	Append‑only internal events	id TEXT PRIMARY KEY, owner_id, task_id, code, occurred_at_utc, metadata_json
snapshots	Bounded diagnostic schedule snapshots	id TEXT PRIMARY KEY, owner_id, operation_name, source_date TEXT, window_json, notice_json, changes_json, retention_expires_utc

• All timestamps are stored as UTC.
• Optimistic concurrency: every mutable row carries revision. Updates must include WHERE revision = :expected and increment on success.
• Drift migrations are generated and tested; downgrades are not supported.

Consequences

• Domain objects remain unchanged; adapters translate.
• Backup library (Block 24) can copy and encrypt this single file.
• Repository contract tests assert schema integrity via Drift introspection.