Architecture Decision Records¶
This directory contains Architecture Decision Records (ADRs) for key design decisions in Qorel.
What is an ADR?¶
An ADR documents a significant architectural decision, including: - Context: Why the decision was needed - Options: What alternatives were considered - Decision: What was chosen - Consequences: Trade-offs and implications
ADR Index¶
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Edge Buffering Strategy | Accepted, amended |
| ADR-002 | Protocol Adapter Architecture | Accepted |
| ADR-003 | Schema Management Strategy | Accepted |
| ADR-004 | Validation and DLQ Workflow | Accepted |
| ADR-005 | Sink Architecture | Accepted |
| ADR-006 | Gateway Autonomy | Accepted |
| ADR-007 | Authentication Model | Accepted |
| ADR-008 | Failure Modes and Recovery | Accepted |
| ADR-009 | Overflow Handling | Accepted |
| ADR-010 | Copilot Tools-First Approach | Accepted, deferred |
| ADR-011 | Phase 1-4 Architecture Conformance Baseline | Accepted |
| ADR-012 | Alerting Rules Storage and Evaluation | Accepted, amended |
| ADR-013 | Escalation Policy Structure and Rule Binding | Accepted, corrected |
| ADR-014 | Alarm Lifecycle | Accepted, corrected |
Key Decisions Summary¶
Data Path¶
- Edge Buffering: Embedded Kafka-compatible broker per gateway, with Redpanda as the chosen edge direction and production packaging still pending
- Serialization: Avro with Schema Registry
- Adapters & Sinks: Docker containers with standard contract
- Overflow: Tiered strategy (compress → downsample → evict by priority)
Architecture¶
- Gateway Autonomy: Full offline capability after first boot
- Validation: Module in Gateway Runtime, BAD → DLQ with operator workflow
- Failure Handling: Restart + bulkhead isolation + circuit breaker
Operations¶
- Authentication: JWT for gateways and built-in users; OAuth/OIDC remains later enterprise work
- AI Copilot: MCP tools-first direction is deferred until core production-readiness work is closed
- Conformance Baseline: Phase 1-4 audit baseline for remediation tracking
- Alerting, Escalation & Alarm Lifecycle: rule-based alarm evaluation (ADR-012), escalation policies with step-walking (ADR-013), and the four-state alarm lifecycle ACTIVE/ACKNOWLEDGED/CLEARED/SUPPRESSED (ADR-014), status maintained in ADR-011 Phase 5
Current implementation progress and issue movement are tracked in: - ADR-011 for open conformance gaps and active checklist items. - Resolved Issues Ledger for items moved out of active queues after completion.
Creating New ADRs¶
When making a significant architectural decision:
-
Copy the template:
cp ADR-TEMPLATE.md ADR-0XX-short-title.md -
Fill in all sections
-
Add to the index above
-
Get team review
ADR Statuses¶
| Status | Meaning |
|---|---|
| Proposed | Under discussion |
| Accepted | Decision made, implementing |
| Deprecated | Superseded by another ADR |
| Rejected | Considered but not chosen |