Architecture Decisions

This page is the decision index for ChokaQ. It explains the major choices behind the runtime and points to the deep dives that defend each choice.

Decision Map

Decision	Why it matters	Deep dive
SQL Server as the durable backend	Keeps accepted work restart-safe and inspectable.	Why SQL Server?
Three Pillars schema	Keeps active work separate from history and recovery evidence.	Three Pillars
At-least-once execution	Honest contract for durable work with external side effects.	Delivery Guarantees
Atomic Hot/Archive/DLQ moves	Prevents half-moved jobs.	Transaction Integrity
UPDLOCK + READPAST fetch	Lets many workers claim work without central locks.	SQL Concurrency
Bounded prefetch	Keeps SQL as backlog and process memory bounded.	Bounded Prefetch
Retry + circuit breaker	Separates per-job retry from systemic failure protection.	Retry And DLQ, Circuit Breakers
DLQ instead of silent drop	Preserves failed work for repair and audit.	Failure Taxonomy
Heartbeat + zombie rescue	Distinguishes healthy long work from dead owners.	Heartbeat
The Deck as an operator surface	Makes repair workflows explicit and safer than ad hoc SQL.	Panel Guide

Decision Quality Bar

Every major decision should be defendable with:

• the problem it solves;
• the operational consequence;
• the trade-off;
• the alternative that was rejected;
• the failure mode that still remains.

Additional Questions

What is the single most important design choice?
Using SQL as the durable coordination boundary. Everything else builds from that: fetch, retry, DLQ, observability, and operations.

What boundary does ChokaQ choose?
ChokaQ is a SQL-backed background job engine with strong operational visibility. It is not designed as a streaming platform, broker mesh, or distributed log.

Where is the hardest correctness boundary?
Between handler side effects and job finalization. ChokaQ protects its own state with transactions, but external side effects require idempotent handler design.