Supporting Reference 7: Design Principles
This page captures the architecture-level decisions that keep the workflow reliable at scale. Use it to evaluate whether a proposed change aligns with system intent.
R7.1 Local-first execution
- Orchestration, queue state, and review loop execute on one local workstation.
- AI prefill uses local Ollama inference for control and privacy.
- Network coupling is intentionally concentrated in publish-only steps.
R7.2 Database-led workflow state
review_queueis source-of-truth for in-flight lifecycle state.- Filesystem paths are treated as assets and artifacts, not state authority.
- Status fields are designed for restartability and incident diagnosis.
R7.3 Deterministic filename integrity
- Filename reservation is managed through
data/used_filenames.json. - Collision prevention is applied before destination writes.
- Rollback/reject flows release names only when safe.
R7.4 Human review as a hard safety gate
- AI outputs are assistive, never autonomous publish authority.
- Review editor remains mandatory before publish.
- Publish is sourced from approved rows only.
R7.5 Fail-fast and recoverable stages
- Stage errors are explicit in logs and state fields.
- Long-running stages are designed to reduce full-run loss when possible.
- Rollback/cleanup exists to restore consistency for safe retries.
R7.6 Packaging-aware resource resolution
- Runtime lookup supports both source execution and packaged EXE contexts.
- Goal: consistent behavior across development, testing, and deployment builds.
R7.7 Design acceptance checks for new changes
- Does this preserve review-first publish behavior?
- Does this keep filename reservation deterministic?
- Does this improve or degrade rollback clarity?
- Is failure visibility better, equal, or worse after the change?
- Does it preserve DB-centered lifecycle observability?