Architecture Overview

KalamDB combines SQL execution, realtime delivery, and multi-tier storage in one runtime.

Major Runtime Layers

• kalamdb-api: HTTP + WebSocket surface (/v1/api/*, /v1/ws)
• kalamdb-core: orchestration, SQL execution flow, authorization checks, job dispatch
• kalamdb-sql: SQL parser/classifier/extensions (SUBSCRIBE, TOPIC, STORAGE, EXECUTE AS USER, etc.)
• kalamdb-store + RocksDB: hot write/read path
• kalamdb-filestore + Parquet: cold segments and manifests
• kalamdb-raft: cluster consensus and replication

Runtime Flow

Data Directory Layout

Default paths are rooted at storage.data_path (usually ./data):

data/
├── rocksdb/      # hot tier
├── storage/      # cold parquet tier
├── snapshots/    # raft snapshots
└── streams/      # stream table logs

Table-specific cold paths are generated from templates:

• shared tables: storage.shared_tables_template
• user tables: storage.user_tables_template

Query Path (Simplified)

1. API receives SQL (POST /v1/api/sql) with bearer auth.
2. SQL is parsed/classified (standard + KalamDB extensions).
3. Authorization and table-type rules are applied.
4. Query executes against hot tier, cold tier, or both.
5. Response returns normalized JSON schema/rows.
6. Optional change notifications flow to subscriptions/topics.

For detailed flush behavior and cold-tier movement, see Storage Tiers.

Technology Stack

Continue Reading

• Storage Tiers
• Table Types
• Clustering & HA
• Data Types