Architecture Decision Records

Architecture Decision Records (ADRs) document significant design decisions made during the development of the Open Job Spec. Each ADR captures the context, decision, and consequences of a choice that shapes the specification.

ADRs are maintained in the spec/adrs/ directory.

Index

ADR	Title	Summary
001	Three-Layer Architecture	Core envelope (Layer 1) → Wire formats (Layer 2) → Protocol bindings (Layer 3), inspired by CloudEvents
002	Eight-State Job Lifecycle	scheduled → available → pending → active → completed/retryable/cancelled/discarded
003	Args (Array) Over Payload (Object)	Using args (JSON array) instead of payload (JSON object) for job arguments
004	UUIDv7 for Job IDs	Time-sortable UUIDs for natural chronological ordering and distributed generation
005	Backend Interface Design	Three-layer internal architecture (API → Core → Storage) for all backends
006	Conformance Level Hierarchy	Five levels (0–4) as progressive supersets, inspired by Unicode conformance
007	Client-Side Encryption Architecture	Codec-based encryption at the SDK layer, keeping backends zero-knowledge
008	Multi-Tenancy Isolation Models	Three models (namespace, shared, hybrid) with hybrid sharded queues recommended
009	Transactional Enqueue Pattern	Outbox pattern for ensuring jobs are only enqueued when the transaction commits
010	Deduplication Strategy	SHA-256 hash of canonical JSON for unique key computation
011	OpenTelemetry-Native Observability	Native OpenTelemetry integration for traces, metrics, and logs
012	Control Plane / Data Plane Separation	Separate admin API path prefix (/ojs/v1/admin/) from data-plane operations
013	NATS JetStream Backend Architecture	JetStream streams + KV stores for a lightweight single-binary backend
014	Kafka Hybrid Backend Architecture	Kafka for transport + Redis for state in a hybrid architecture
015	SQS + DynamoDB Backend Architecture	AWS-native backend using SQS for transport and DynamoDB for state

ADR Format

Each ADR follows a standard structure:

1. Status — Proposed, Accepted, Deprecated, or Superseded
2. Context — The situation and forces driving the decision
3. Decision — What was decided and why
4. Consequences — Positive and negative outcomes of the decision
5. Alternatives Considered — Other options that were evaluated

Creating New ADRs

New ADRs follow the RFC process. To propose an architecture decision:

1. Create a new ADR file following the template in spec/adrs/README.md
2. Submit a pull request with the proposal
3. Discuss in the PR and gather feedback
4. ADR is accepted when consensus is reached

See the RFC Process for the full contribution workflow.