focus-flow/Codex Documentation/Current Software Plan/V1_ADR_003_Runtime_Topology_Embedded_Local.md

V1 ADR 003: Embedded Local Runtime Topology

Status: Accepted
Date: 2026-06-26

Context

With SQLite as the local persistence engine, V1 no longer requires a separate service process. The entire stack can run inside a single Flutter/Dart desktop binary.

Decision

• Embedded DB – The application opens an on‑disk SQLite file via Drift.
• No background daemon – starting the desktop app is enough; automated tests use an in‑memory or temporary‑file database.
• Dev hot‑reload – scripts/dev.sh launches Flutter desktop and watches Drift files.
• Pluggable adapters – A future remote/sync adapter will satisfy the same repository interfaces; switching happens at composition root.

Rejected

• Running a local Node.js or Go service to host SQLite – unnecessary complexity.
• Direct file writes bypassing Drift – loses migration guarantees.

Consequences

• Deployment simplifies to one executable per platform.
• CI can run integration tests without Docker or external DB.