ADR-002: File-Backed Run History Store Before Database Persistence
- Status: Proposed
- Date: 2026-04-14
Context
The first slice creates exactly one terminal RunSummary per run and exposes only LastRunSummary in the central app state.
The next valuable capability is to preserve those summaries across app restarts so operators and developers can review recent history without introducing a database too early.
This decision should favor:
- low implementation complexity
- easy AI-assisted delivery
- testability
- a realistic but modest persistence boundary
Decision
For the next slice, persist run history to a file-backed store behind an application abstraction.
For the first persisted-history version:
- use a repository or store interface in the application layer
- implement a file-backed JSON store in infrastructure
- keep the file path configurable so tests can use temporary locations
- load history on startup
- append or upsert entries by
RunId - expose history to the UI through canonical app state
Database persistence is deferred to a later slice.
Rationale
This choice keeps the project aligned with the prototype scope while still introducing realistic persistence concerns:
- startup hydration
- file I/O failure handling
- corruption tolerance
- atomic-ish writes
- separation between application policy and infrastructure storage
It is also small enough to be implemented in focused AI-assisted tasks without dragging in database setup, migrations, or operational concerns too early.
Consequences
Positive
- run history becomes durable across app restarts
- the persistence seam is explicit and testable
- future migration to database persistence remains possible
- the UI can evolve from one summary to a proper history list
Trade-Offs
- file corruption and partial-write handling must be considered
- concurrent write policy must be defined clearly
- this is not suitable for enterprise-scale reporting or multi-user scenarios
Non-Goals
This ADR does not choose:
- a database engine
- long-term analytics storage
- multi-machine history aggregation
- advanced filtering or search