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.
• Classifier-assisted subject/metadata hints run locally via CLIP zero-shot image classification (with optional model fallback and Stage 6 timeout/quarantine guards in code).
• Network coupling is intentionally concentrated in publish-only steps.

R7.2 Database-led workflow state

• review_queue is 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.
• Review editor supports per-row metadata regeneration (Generate) without bypassing manual approve/reject control.
• Regeneration includes duplicate-caption protection against pending rows.
• 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.
• Prefill QC writes a machine-readable report to data/prefill_qc_last.json before the editor opens.
• 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.
• Startup log emits Ollama runtime mode visibility (processor=GPU/CPU, context, and VRAM).
• Run-end Ollama shutdown can be controlled by OLLAMA_CLOSE_ON_RUN_END.
• Goal: consistent behavior across development, testing, and deployment builds.

R7.7 Design acceptance checks for new changes

1. Does this preserve review-first publish behavior?
2. Does this keep filename reservation deterministic?
3. Does this improve or degrade rollback clarity?
4. Is failure visibility better, equal, or worse after the change?
5. Does it preserve DB-centered lifecycle observability?

R7.8 Continuation path