eva/focus-flow
6
0
Fork 1
Code Issues 14 Pull requests 1 Projects Releases Packages Wiki Activity Actions 1
focus-flow/Codex Documentation/Completed Plans/V1_ADR_002_SQLite_Document_Schema_V1.md

3.9 KiB
Raw Blame History

V1 ADR 002: SQLite Document Schema V2

Status: Accepted; updated to match current app state

Date: 2026-06-26

Last reviewed: 2026-07-07

Context

The project is SQLite-first. The local app persists scheduler state in a Drift database and keeps storage details behind repository and application-unit-of-work boundaries.

The original V1 schema was implemented and then migrated to the current Drift schema version 2 when application-layer records became durable state.

Decision

  • Database file: scheduler.sqlite under ~/ADHD_Scheduler/ by default. Runtime composition may override this with SCHEDULER_SQLITE_PATH, and dev tooling may pass --sqlite.
  • Schema version: 2, managed by Drift. Version 1 files are supported as migration inputs; downgrades are not supported.
  • Tables
Table Purpose Key fields
tasks Authoritative task rows id TEXT PRIMARY KEY, owner_id, title, project_id, parent_id, type, status, priority, reward, difficulty, duration_minutes, scheduled/actual/completed UTC timestamps, backlog_tags_json, reminder_override, stats_json, backlog_entered_at_utc, backlog_entered_provenance, revision, created_at_utc, updated_at_utc
task_activities Append-only task activity facts id TEXT PRIMARY KEY, owner_id, task_id, project_id, operation_id, code, occurred_at_utc, metadata_json
projects Project configuration id TEXT PRIMARY KEY, owner_id, name, color_key, configured defaults, archived_at_utc, revision, created_at_utc, updated_at_utc
project_statistics Project-level aggregate statistics project_id PRIMARY KEY, owner_id, completion and suggestion-count fields, revision, created_at_utc, updated_at_utc
locked_blocks Recurring / one-off locked time id TEXT PRIMARY KEY, owner_id, name, date, start_time, end_time, recurrence_json, hidden_by_default, project_id, archived_at_utc, revision, timestamps
locked_overrides Date-scoped locked-block overrides id TEXT PRIMARY KEY, owner_id, locked_block_id, date, override type and payload fields
settings One row per owner owner_id TEXT PRIMARY KEY, timezone_id, day_start_minutes, day_end_minutes, compact_mode, backlog_staleness_json, revision, timestamps
snapshots Bounded diagnostic schedule snapshots id TEXT PRIMARY KEY, owner_id, captured_at_utc, operation_name, source_date, target_date, JSON payload columns, retention_expires_utc, truncated, revision, timestamps
application_operations Committed operation records for idempotency operation_id TEXT PRIMARY KEY, owner_id, operation_name, committed_at_utc
notice_acknowledgements Owner-scoped acknowledged notice records composite key owner_id, notice_id, acknowledged_at_utc, revision, timestamps
  • UTC timestamps are stored in Drift DateTime columns. Civil dates and wall times remain text fields where the domain model requires calendar-local values.
  • Mutable domain/application records carry optimistic revision values. Updates must compare the expected revision and increment on success. Append-only activity and operation records are immutable facts and do not use mutable-save revision checks.
  • Schema version 2 migrations create the application-layer tables and indexes needed for task activity, project statistics, idempotent operations, and notice acknowledgements.

Consequences

  • Domain objects remain unchanged; adapters translate between domain objects and SQLite rows.
  • The backup library copies and encrypts this single SQLite file.
  • Repository conformance tests cover adapter behavior, while Drift schema tests verify version 2 tables and version 1 upgrade behavior.