ADR-003: Use JSON Recipe Catalog Before In-App Editor
- Status: Proposed
- Date: 2026-04-16
Context
The first slice uses seeded in-memory recipes so the runtime can be demonstrated without file I/O.
That was the right choice early on, but the next meaningful step is to let operators and developers work with recipe files outside the codebase.
At the same time, a full in-app recipe editor would be too large for the next slice and would mix file management, editing UX, validation UX, and persistence concerns together.
The next decision should favor:
- realistic external recipe files
- low implementation complexity
- easy AI-assisted delivery
- clear validation behavior
- stable application and UI boundaries
Decision
For the next slice, introduce a file-backed JSON recipe catalog behind an application abstraction.
For the first recipe-file version:
- recipes live as JSON files in a configurable folder
- the application depends on a recipe catalog abstraction rather than direct file access
- infrastructure implements folder scanning, JSON parsing, and validation
- invalid files are skipped and surfaced through diagnostics or logs
- the UI loads only validated recipes into canonical app state
- in-app editing and saving are deferred to a later slice
Rationale
This choice adds realistic file-based workflow without overcommitting to a large editor feature too early.
It fits the prototype well because it introduces:
- file discovery
- schema validation
- operator refresh behavior
- diagnostics for bad inputs
- a clearer boundary between runtime policy and storage concerns
It is also small enough to split into focused AI-friendly tasks.
Consequences
Positive
- recipes can evolve without recompiling the app
- developers can test realistic good and bad recipe files
- the application boundary becomes more believable for future expansion
- later editor work can build on the same catalog boundary
Trade-Offs
- file schema validation rules must be defined clearly
- the app must decide how to behave when files are missing or invalid
- this does not yet provide an operator-friendly editing experience
Non-Goals
This ADR does not choose:
- an in-app recipe editor
- version migration strategy for complex schemas
- recipe persistence back to disk from the UI
- enterprise recipe approval workflows