Architecture Decision Records (ADR) Index

This directory serves as the central knowledge base for Quickwit architecture.

Knowledge Map (Agent Context)

For AI agents and developers, here is how the system is organized by domain:

Core Architecture

ADRs will be created here as we implement new systems. Start with the metrics pipeline and work outward.

Signal Priority

Metrics first, then traces, then logs. Architectural decisions must generalize across all three signals.

Master Index

ADR	Title	Status	Tags	Key Components
000	Template	-	`meta`	-
001	Parquet Metrics Data Model	Proposed	`storage`, `metrics`, `parquet`, `data-model`	quickwit-parquet-engine
002	Configurable Sort Schema for Parquet Splits	Proposed	`storage`, `metrics`, `compaction`, `parquet`, `sorting`	quickwit-parquet-engine, quickwit-indexing
003	Time-Windowed Sorted Compaction for Parquet	Proposed	`storage`, `metrics`, `compaction`, `parquet`, `time-windowing`	quickwit-parquet-engine, quickwit-indexing, quickwit-metastore

Supplements & Roadmaps

Detailed implementation plans and reports linked to ADRs.

Parent ADR	Supplement	Description
000	Supplement Template	Template for new supplements

Architecture Evolution

Quickwit tracks architectural change through three lenses. See EVOLUTION.md for the full process.

                    Architecture Evolution
                            │
       ┌────────────────────┼────────────────────┐
       ▼                    ▼                    ▼
 Characteristics          Gaps              Deviations
  (Proactive)          (Reactive)          (Pragmatic)

Characteristics (What we need)

Product requirements and capabilities we must have.

Gaps (What we learned)

Gap	Title	Status	Severity
001	No Parquet Split Compaction	Open	High
002	Fixed Hardcoded Sort Schema	Open	Medium
003	No Time-Window Partitioning at Ingestion	Open	High
004	Incomplete Split Metadata for Compaction	Open	High
005	No Per-Point Deduplication	Open	Medium
006	No Independent Auto-Scaling	Open	High
007	No Parquet Metadata Caching	Open	High
008	No High Query Rate Optimization	Open	High
009	No Leading Edge Prioritization	Open	High
010	No Multi-Level Data Caching or Query Affinity Optimization	Open	High

Create a gap when you discover a design limitation from production, incidents, or research. See gaps/README.md.

Deviations (What we accepted)

Deviation	Title	Related ADR	Priority

No deviations recorded yet.

Create a deviation when implementation intentionally differs from ADR intent. See deviations/README.md.

Decision Logs (How to use)

We do not have a separate "Decision Log" file. Decision Logs are embedded in each ADR.

When you need to understand why a decision was made:

Find the relevant ADR in the Knowledge Map above.
Scroll to the Decision Log section at the bottom of that ADR.
If making a NEW decision, update that table.

Status Definitions

Proposed: Under discussion, awaiting prototype or review.
Accepted: Approved plan of record. Implementation should follow this.
Deprecated: Replaced or abandoned. Kept for history.
Superseded: Replaced by a newer ADR (see link).