Because someone decided that two years ago.

Use workflow engine.
No, use event choreography.
No, use Temporal.
No, use Camunda.
No, use simple services.

Decision:
Use Camunda 7 as a workflow orchestration service for long-running order fulfillment.

Context:
- order fulfillment has human tasks, timers, retries, escalation, and fallout;
- the enterprise already operates Camunda 7;
- running process instances must be visible to operations;
- workflow variables must not become domain state;
- Camunda 7 has lifecycle constraints, so a migration fence is required.

Rejected alternatives:
- pure Kafka choreography;
- custom workflow tables;
- synchronous orchestration inside Order Service;
- immediate Camunda 8 adoption.

Consequences:
- workflow-service becomes runtime owner of process execution;
- order-service remains authority for order state;
- process variables are minimal;
- every instance uses business key;
- external tasks must be idempotent;
- migration fence is mandatory.

Use LocalDateTime in this mapper.

Use deterministic Clock abstraction for all command handlers that create lifecycle evidence.

Status: Proposed | Accepted | Rejected | Superseded | Deprecated

# ADR-0007: Use Transactional Outbox for Domain Event Publication

Date: 2026-07-02

Status: Accepted

## Context

What problem are we solving?
What constraints exist?
What has changed?
Why does the decision matter now?

## Decision

What did we choose?
State it directly.

## Alternatives Considered

### Option A: Publish event directly inside service transaction

Pros:
- simple code path

Cons:
- dual-write risk
- event may publish without DB commit
- DB may commit without event publish

### Option B: Transactional outbox with polling publisher

Pros:
- event record commits in same DB transaction as aggregate mutation
- publisher can retry independently
- replay and monitoring are possible

Cons:
- additional table and publisher process
- eventual publication, not immediate publication
- cleanup/retention required

## Consequences

What gets better?
What gets worse?
What new obligations exist?

## Invariants Protected

Which business/technical invariants does this decision protect?

## Revisit Triggers

When should we reconsider?

## References

Links to code, docs, tickets, BPMN, OpenAPI, schema, runbook.

repo-root/
  docs/
    adr/
      0001-record-architecture-decisions.md
      0002-use-openapi-first-for-service-contracts.md
      0003-use-postgresql-as-system-of-record.md
      0004-use-camunda-7-for-workflow-orchestration.md
      0005-use-transactional-outbox-for-events.md
      0006-use-quote-revision-snapshots.md
      0007-use-redis-only-as-non-authoritative-accelerator.md
    architecture/
      system-context.md
      service-boundaries.md
      runtime-topology.md
    runbooks/
      order-fallout.md
      camunda-incident-recovery.md
      kafka-replay.md

<sequence>-<short-slug>.md

0012-use-camunda-business-key-for-workflow-correlation.md

Decision: Use Redis for performance.

Decision: Use Redis cache-aside for product catalog read projections only.

Protected invariant:
Quote acceptance must not depend on Redis content.

Failure mode reduced:
High repeated catalog read latency during configuration sessions.

New failure mode:
Stale catalog projection may be shown to user.

Control:
Cache key includes tenantId + catalogPublicationId + productOfferingId.
TTL is 15 minutes.
Publication event invalidates keys.
Quote submit validates against PostgreSQL catalog snapshot.

Test:
Catalog cache stale scenario must fail safe at quote submit.

Metric:
Catalog cache hit ratio, stale validation rejection count, Redis latency, fallback read latency.

PR: Implement quote revision immutability

Changes:
- docs/adr/0011-use-immutable-quote-revisions.md
- quote-service/src/main/java/.../SubmitQuoteCommandHandler.java
- quote-service/src/main/resources/db/migration/V031__quote_revision_constraints.sql
- quote-service/src/test/java/.../SubmitQuoteConcurrencyTest.java
- openapi/quote-service.yaml

# ADR-0011: Use Immutable Quote Revisions After Submission

Date: 2026-07-02
Status: Accepted

## Context

A quote can be edited while in DRAFT.
After it is submitted for pricing/approval, commercial evidence starts to accumulate:
price result, approval requirement, approval decision, document artifact, and customer acceptance.
If the same quote revision remains mutable, old evidence can point to changed commercial content.

## Decision

After a quote revision leaves DRAFT, material commercial content becomes immutable.
Any material change creates a new quote revision.

## Alternatives Considered

### Mutable quote with audit log

Pros:
- simpler UI mental model
- fewer rows

Cons:
- price/approval/document evidence can become stale or misleading
- audit reconstruction becomes complex
- concurrent edit/approval race is harder

### Immutable revision with new revision on material change

Pros:
- evidence is bound to stable content
- approval freshness is enforceable
- accepted quote can be reproduced
- order conversion has a clear source revision

Cons:
- UI must expose revision history
- storage grows
- amend/revise flows need explicit commands

## Consequences

- quote_revision is the aggregate root for submitted commercial evidence.
- price_result references quote_revision_id.
- approval_decision references quote_revision_id.
- document_artifact references quote_revision_id.
- accepted quote revision can create at most one primary order.

# ADR-0018: Treat Camunda 7 Process Variables as Workflow Context, Not Domain State

Date: 2026-07-02
Status: Accepted

## Context

Order fulfillment is orchestrated by Camunda 7.
Process instances need variables for routing, task assignment, worker calls, and correlation.
If full order state is copied into process variables, Camunda history becomes a second source of truth.

## Decision

Camunda variables may store only minimal workflow context:
- tenantId
- orderId
- orderRevision or orderVersion
- businessKey
- fulfillmentPlanId
- current step identifiers
- correlation IDs
- non-authoritative routing hints

Order state remains in Order Service PostgreSQL tables.

## Consequences

- external task workers load fresh order state from Order Service.
- workflow can route but cannot invent business truth.
- process instance migration is simpler.
- operational debugging requires correlation to domain read model.

# ADR-0023: Use Asynchronous Billing Handoff With Reconciliation

Date: 2026-07-02
Status: Accepted

## Context

Order fulfillment eventually needs billing activation.
Billing system owns invoices, charges, tax handling, receivables, and payment status.
OMS owns order lifecycle and billing handoff state.
Synchronous billing activation would couple order completion latency to billing availability.

## Decision

OMS emits BillingActivationRequested through Kafka after order line reaches BILLING_READY.
Billing responds through BillingActivationAccepted, BillingActivationRejected, or status query reconciliation.
OMS tracks billing handoff state locally and creates fallout after SLA breach.

## Consequences

- order lifecycle can represent BILLING_PENDING.
- OMS must reconcile unknown handoff outcomes.
- billing request uses business idempotency key.
- billing events must include orderId, orderLineId, tenantId, requestId, and billingSystemReference if known.

# ADR-0028: Use Projection Tables for Quote and Order Operational Search

Date: 2026-07-02
Status: Accepted

## Context

Operations need fast search across quote/order/workflow fields.
The write model is normalized around lifecycle correctness.
Using write tables directly for search would create complex joins and authorization leakage risk.

## Decision

Use projection tables for operational search.
Projection tables are rebuilt from authoritative domain tables and events.
They are derived, not authoritative.

## Consequences

- projection lag must be visible.
- command decisions must not depend on projection tables.
- projection rebuild job is required.
- search API must expose freshness metadata.

This table was originally a report table, but now some commands depend on it.

# ADR-0031: Enforce Object-Level Authorization in Every Quote Command

Date: 2026-07-02
Status: Accepted

## Context

Quote IDs are opaque but not security boundaries.
Users may belong to different tenants, sales regions, teams, accounts, or delegated approval groups.
A user who can access one quote must not automatically access another quote.

## Decision

Every quote command handler must perform object-level authorization using tenant, account relationship, user role, delegation, and lifecycle-specific permission.
Gateway authentication is necessary but insufficient.

## Consequences

- command handlers receive AuthContext.
- repositories must be tenant-scoped.
- authorization denial is audited.
- search projections must be filtered by entitlement.
- tests must include cross-tenant and cross-account access attempts.

# ADR-0038: Map Exhausted Order Workflow Failures to Fallout Cases

Date: 2026-07-02
Status: Accepted

## Context

Camunda external tasks can fail because of retryable technical errors, rejected business conditions, unknown external outcomes, or permanent integration faults.
Leaving incidents only in Camunda Cockpit is insufficient for case workers.

## Decision

When retry policy is exhausted for order fulfillment tasks, Workflow Service creates a domain fallout case linked to orderId, processInstanceId, activityId, externalTaskId, and last failure classification.

## Consequences

- operations uses fallout worklist as primary recovery queue.
- Camunda incident remains technical evidence.
- recovery actions must be domain-safe commands.
- manual retry is audited.

We choose Camunda 7 orchestration because the order fulfillment domain requires visible long-running processes, human recovery, timers, and incident handling. We accept platform lifecycle risk and mitigate it with a migration fence and minimal process variable model.

This improves maintainability and scalability.

Positive consequences:
- Quote acceptance can reproduce the exact approved commercial content.
- Approval decisions remain bound to a stable revision.
- Order conversion can enforce one primary order per accepted revision.

Negative consequences:
- Users must understand revision history.
- Storage grows with revision count.
- UI must show stale approval and stale price reasons clearly.
- Migration from mutable quote rows requires snapshot backfill.

Operational consequences:
- Support must inspect quote revision, not quote header only.
- Audit reports must group by quoteId and quoteRevisionId.
- Search projection must expose latest revision and accepted revision separately.

Revisit this decision if:
- order workflow volume exceeds Camunda 7 job executor capacity after tuning;
- process migration becomes frequent enough to slow release cadence;
- business process modeling needs exceed BPMN/DMN maintainability;
- enterprise platform strategy mandates Camunda 8 migration;
- workflow-service becomes a domain state authority despite boundary controls.

# Architecture Decision Records

| ADR | Status | Title | Area | Supersedes | Last Reviewed |
|---|---|---|---|---|---|
| 0001 | Accepted | Record architecture decisions | Governance | - | 2026-07-02 |
| 0002 | Accepted | Use OpenAPI-first for service contracts | API | - | 2026-07-02 |
| 0003 | Accepted | Use PostgreSQL as authoritative lifecycle store | Data | - | 2026-07-02 |
| 0004 | Accepted | Use Camunda 7 for order workflow orchestration | Workflow | - | 2026-07-02 |
| 0005 | Accepted | Use transactional outbox for event publication | Events | - | 2026-07-02 |
| 0006 | Accepted | Use immutable quote revisions | Domain | - | 2026-07-02 |
| 0007 | Accepted | Use Redis only as non-authoritative accelerator | Cache | - | 2026-07-02 |

ADR-0001: Record architecture decisions
ADR-0002: Use ADR statuses and supersession instead of editing history
ADR-0003: Store ADRs in repository under docs/adr

ADR-0010: Use bounded services around business capabilities, not database entities
ADR-0011: Separate CPQ commercial intent from OMS fulfillment obligation
ADR-0012: Use BFF for frontend composition without business authority

ADR-0020: Use OpenAPI-first for HTTP APIs
ADR-0021: Use schema-first event contracts
ADR-0022: Use RFC 9457-style problem detail errors
ADR-0023: Use idempotency key for lifecycle commands
ADR-0024: Use ETag/If-Match for optimistic command protection where applicable

ADR-0030: PostgreSQL is authoritative lifecycle store
ADR-0031: Use immutable quote revision snapshots
ADR-0032: Snapshot price result at quote revision
ADR-0033: Use append-only audit evidence
ADR-0034: Use transactional outbox for integration events
ADR-0035: Keep read models derived and rebuildable
ADR-0036: Use expand-migrate-contract for schema evolution

ADR-0040: Use Camunda 7 as workflow orchestration service
ADR-0041: Process variables are not domain state
ADR-0042: Use business key for quote/order workflow correlation
ADR-0043: Use external task workers for integration-side effects
ADR-0044: Map exhausted workflow failure to fallout case
ADR-0045: Define process migration and versioning policy

ADR-0050: Kafka events are committed business/integration facts
ADR-0051: Topic ownership follows producer domain ownership
ADR-0052: Partition by aggregate identity where order matters
ADR-0053: Consumers must be idempotent
ADR-0054: DLQ is a lifecycle, not a trash bin

ADR-0060: Redis is non-authoritative accelerator
ADR-0061: Catalog cache keys include publication/version identity
ADR-0062: Cache TTL is safety net, not correctness mechanism
ADR-0063: Do not depend on Redis locks for lifecycle correctness

ADR-0070: Enforce tenant isolation in every persistence and integration boundary
ADR-0071: Enforce object-level authorization in command handlers
ADR-0072: Approval authority is policy-driven and auditable
ADR-0073: Control plane operations require privileged scoped roles

ADR-0080: Use production readiness review before launch
ADR-0081: Define SLOs for critical CPQ/OMS journeys
ADR-0082: Define backup/restore and reconciliation drill obligations
ADR-0083: Define incident classification and escalation policy
ADR-0084: Define replay/backfill policy for events and projections

ADR becomes justification, not decision memory.

Approved by architecture board.

Use Kafka.

metric, log, dashboard, alert, reconciliation job, or audit report

[ ] Is the decision stated in one direct sentence?
[ ] Is the context specific to this platform?
[ ] Are alternatives described fairly?
[ ] Are negative consequences explicit?
[ ] Are protected invariants named?
[ ] Are new failure modes named?
[ ] Are operational obligations named?
[ ] Are tests or controls named?
[ ] Are migration implications named?
[ ] Are security/tenant impacts considered?
[ ] Are revisit triggers defined?
[ ] Does it link to relevant specs/code/runbooks?
[ ] Does it avoid vague claims like scalable, maintainable, flexible without evidence?

# ADR-0020: Use OpenAPI-First for HTTP Service Contracts

Date: 2026-07-02
Status: Accepted

## Context

The CPQ/OMS platform has multiple services, BFF clients, integration consumers, generated DTOs, and contract tests.
If HTTP contracts are implemented first and documented later, client/server compatibility becomes accidental.

## Decision

All external and cross-service HTTP APIs are defined in OpenAPI before implementation.
Generated DTOs and interface stubs may be used at adapter boundaries, but generated objects must not become domain entities.

## Alternatives Considered

### Code-first API

Pros:
- fast initial implementation
- less contract ceremony

Cons:
- contract drift
- weaker review of lifecycle semantics
- harder compatibility gates

### OpenAPI-first API

Pros:
- explicit contract review
- generated clients/stubs possible
- compatibility checks in CI
- clearer BFF/service boundary

Cons:
- requires design discipline
- schema changes need governance
- generated code boundary must be managed

## Consequences

- OpenAPI spec changes are reviewed as product/API changes.
- Command endpoints must model lifecycle intent.
- Error responses use shared problem details schema.
- Breaking changes require versioning or migration plan.

# ADR-0034: Use Transactional Outbox for Event Publication

Date: 2026-07-02
Status: Accepted

## Context

Domain services must update PostgreSQL state and publish Kafka events.
Direct DB update plus direct Kafka publish creates dual-write risk.

## Decision

Domain services write outbox rows in the same transaction as aggregate state changes.
A publisher process reads outbox rows and publishes Kafka events.
Consumers must be idempotent.

## Consequences

- Event publication is eventually consistent.
- Outbox lag becomes an operational metric.
- Outbox cleanup and retry are required.
- Event order is preserved per aggregate where publisher policy enforces it.

# ADR-0045: Introduce Migration Fence Around Camunda 7

Date: 2026-07-02
Status: Accepted

## Context

Camunda 7 is used for workflow orchestration.
The platform needs long-running processes, user tasks, timers, incidents, and operator visibility.
Camunda 7 lifecycle constraints mean the platform should avoid deep coupling to engine internals.

## Decision

All domain services interact with workflow through Workflow Service APIs and events.
Only Workflow Service uses Camunda 7 engine APIs directly.
BPMN process variables remain minimal.
Domain state remains outside Camunda.

## Consequences

- Future migration to another workflow runtime is possible but not free.
- Workflow Service becomes an anti-corruption layer.
- External task workers must use stable worker contracts.
- Raw Camunda APIs are not exposed to product services or frontend.

1. Engineer identifies material decision.
2. Engineer writes Proposed ADR.
3. Team reviews in normal PR.
4. Required stakeholders comment.
5. ADR is accepted, rejected, or revised.
6. Implementation links to ADR.
7. ADR index is updated.
8. ADR is reviewed during major redesign or production incident.

Order fulfillment worker retried ReserveInventory after timeout.
External inventory had actually reserved stock, but response was lost.
Retry created duplicate reservation.

ADR-0091: Treat inventory reservation timeout as unknown outcome requiring status reconciliation before retry.

- ReserveInventory command stores externalRequestId.
- Worker queries reservation status before retrying after timeout.
- Fallout created if inventory status cannot be determined within SLA.
- Duplicate reservation test is added.

[ ] System boundary and service ownership
[ ] OpenAPI-first contract strategy
[ ] Schema-first event strategy
[ ] PostgreSQL authority and schema evolution
[ ] JPA aggregate and transaction boundary
[ ] Quote revision immutability
[ ] Pricing snapshot and trace
[ ] Approval freshness and authority
[ ] Order lifecycle and fulfillment orchestration
[ ] Camunda 7 topology and migration fence
[ ] Transactional outbox
[ ] Kafka topic and replay policy
[ ] Redis non-authority policy
[ ] Tenant isolation and object authorization
[ ] Audit evidence model
[ ] Fallout and manual recovery model
[ ] Production readiness bar

What changed in the code?

Why is the system shaped this way?

if (!quoteRevision.isDraft()) {
    throw new ConflictException("QUOTE_REVISION_IMMUTABLE");
}

Because price, approval, document, and acceptance evidence must stay bound to stable commercial content.

Can we build this?

Can future teams understand why we built it this way?
Can operations recover it?
Can security review it?
Can auditors trace it?
Can we safely change it later?