# andrealaforgia/kaleidoscope architecture

> Architecture diagram of the GitHub repository andrealaforgia/kaleidoscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrealaforgia/kaleidoscope
- Repository: https://github.com/andrealaforgia/kaleidoscope

## Overview

Kaleidoscope is an OpenTelemetry-compatible observability platform: applications send telemetry for durable storage, while operators manage platform configuration and users query and visualize signals. The README documents alerting, sampling, schema, anomaly detection, identity, cold storage, and profiles as platform capabilities, so these remain visible alongside the sampled ingest and read paths. Several feature implementations and their exact wiring were not sampled; those subsystems are shown without speculative call edges.

Main entry points: [`crates/aperture-storage-sink/src/lib.rs`](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture-storage-sink/src/lib.rs) (Signal sinks), [`apps/prism/src/app/App.tsx`](https://github.com/andrealaforgia/kaleidoscope/blob/main/apps/prism/src/app/App.tsx) (Prism explorers), [`crates/aperture/src/app.rs`](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture/src/app.rs) (Ingest transport), [`crates/kaleidoscope-gateway/src/main.rs`](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/kaleidoscope-gateway/src/main.rs) (OTLP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingest and processing"]
  node_gateway["OTLP gateway<br/>[main.rs]"]
  node_aperture["Ingest transport<br/>[app.rs]"]
  node_conformance["OTLP validation<br/>[lib.rs]"]
  node_sampling["Trace sampling<br/>[lib.rs]"]
  node_sink["Signal sinks<br/>[lib.rs]"]
end

subgraph group_storage["Signal storage"]
  node_lumen[("Log store<br/>[lib.rs]")]
  node_pulse[("Metric store<br/>[lib.rs]")]
  node_ray[("Trace store<br/>[lib.rs]")]
  node_strata[("Profile store<br/>[lib.rs]")]
  node_cinder[("Cold storage<br/>[lib.rs]")]
end

subgraph group_query["Query and visualization"]
  node_metrics_api["Metrics query API<br/>[main.rs]"]
  node_logs_api["Logs query API<br/>[main.rs]"]
  node_traces_api["Traces query API<br/>[main.rs]"]
  node_prism["Prism explorers<br/>[App.tsx]"]
end

subgraph group_operations["Operations and alerts"]
  node_beacon["Alert evaluation<br/>[lib.rs]"]
  node_beacon_state[("Alert state<br/>[state_store.rs]")]
  node_loom["Rule change control<br/>[lib.rs]"]
end

subgraph group_platform["Platform capabilities"]
  node_augur["Anomaly detection<br/>[lib.rs]"]
  node_codex["Schema catalogue<br/>[catalogue.rs]"]
  node_aegis["Identity validation<br/>[lib.rs]"]
  node_spark["Resource identity<br/>[lib.rs]"]
end

node_apps(("Instrumented apps"))
node_analyst(("Analyst"))
node_operator(("Platform operator"))

node_apps -->|"send OTLP"| node_gateway
node_gateway -->|"starts ingest"| node_aperture
node_aperture -->|"validates signals"| node_conformance
node_aperture -->|"dispatches records"| node_sink
node_sink -->|"writes logs"| node_lumen
node_sink -->|"writes metrics"| node_pulse
node_sink -->|"writes traces"| node_ray
node_metrics_api -->|"reads metrics"| node_pulse
node_logs_api -->|"reads logs"| node_lumen
node_traces_api -->|"reads traces"| node_ray
node_analyst -->|"explores signals"| node_prism
node_prism -->|"queries metrics"| node_metrics_api
node_prism -->|"queries logs"| node_logs_api
node_prism -->|"queries traces"| node_traces_api
node_operator -->|"plans rule changes"| node_loom
node_beacon -->|"persists rule state"| node_beacon_state

click node_gateway "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/kaleidoscope-gateway/src/main.rs"
click node_aperture "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture/src/app.rs"
click node_conformance "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/otlp-conformance-harness/src/lib.rs"
click node_sampling "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/sieve/src/lib.rs"
click node_sink "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture-storage-sink/src/lib.rs"
click node_lumen "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/lumen/src/lib.rs"
click node_pulse "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/pulse/src/lib.rs"
click node_ray "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/ray/src/lib.rs"
click node_strata "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/strata/src/lib.rs"
click node_cinder "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/cinder/src/lib.rs"
click node_metrics_api "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/query-api/src/main.rs"
click node_logs_api "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/log-query-api/src/main.rs"
click node_traces_api "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/trace-query-api/src/main.rs"
click node_prism "https://github.com/andrealaforgia/kaleidoscope/blob/main/apps/prism/src/app/App.tsx"
click node_beacon "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/beacon/src/lib.rs"
click node_beacon_state "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/beacon/src/state_store.rs"
click node_loom "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/loom/src/lib.rs"
click node_augur "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/augur/src/lib.rs"
click node_codex "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/codex/src/catalogue.rs"
click node_aegis "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aegis/src/lib.rs"
click node_spark "https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/spark/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_aperture,node_conformance,node_sampling,node_sink toneBlue
class node_lumen,node_pulse,node_ray,node_strata,node_cinder toneAmber
class node_metrics_api,node_logs_api,node_traces_api,node_prism toneMint
class node_beacon,node_beacon_state,node_loom toneRose
class node_augur,node_codex,node_aegis,node_spark,node_apps,node_analyst,node_operator toneIndigo
```

## Components

### Ingest and processing

- [OTLP gateway](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/kaleidoscope-gateway/src/main.rs): `crates/kaleidoscope-gateway/src/main.rs`
- [Ingest transport](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture/src/app.rs): `crates/aperture/src/app.rs`
- [OTLP validation](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/otlp-conformance-harness/src/lib.rs): `crates/otlp-conformance-harness/src/lib.rs`
- [Trace sampling](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/sieve/src/lib.rs): `crates/sieve/src/lib.rs`
- [Signal sinks](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aperture-storage-sink/src/lib.rs): `crates/aperture-storage-sink/src/lib.rs`

### Signal storage

- [Log store](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/lumen/src/lib.rs): `crates/lumen/src/lib.rs`
- [Metric store](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/pulse/src/lib.rs): `crates/pulse/src/lib.rs`
- [Trace store](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/ray/src/lib.rs): `crates/ray/src/lib.rs`
- [Profile store](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/strata/src/lib.rs): `crates/strata/src/lib.rs`
- [Cold storage](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/cinder/src/lib.rs): `crates/cinder/src/lib.rs`

### Query and visualization

- [Metrics query API](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/query-api/src/main.rs): `crates/query-api/src/main.rs`
- [Logs query API](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/log-query-api/src/main.rs): `crates/log-query-api/src/main.rs`
- [Traces query API](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/trace-query-api/src/main.rs): `crates/trace-query-api/src/main.rs`
- [Prism explorers](https://github.com/andrealaforgia/kaleidoscope/blob/main/apps/prism/src/app/App.tsx): `apps/prism/src/app/App.tsx`

### Operations and alerts

- [Alert evaluation](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/beacon/src/lib.rs): `crates/beacon/src/lib.rs`
- [Alert state](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/beacon/src/state_store.rs): `crates/beacon/src/state_store.rs`
- [Rule change control](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/loom/src/lib.rs): `crates/loom/src/lib.rs`

### Platform capabilities

- [Anomaly detection](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/augur/src/lib.rs): `crates/augur/src/lib.rs`
- [Schema catalogue](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/codex/src/catalogue.rs): `crates/codex/src/catalogue.rs`
- [Identity validation](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/aegis/src/lib.rs): `crates/aegis/src/lib.rs`
- [Resource identity](https://github.com/andrealaforgia/kaleidoscope/blob/main/crates/spark/src/lib.rs): `crates/spark/src/lib.rs`

### Other components

- **Instrumented apps**
- **Analyst**
- **Platform operator**

## Connections

- Instrumented apps → OTLP gateway: send OTLP
- OTLP gateway → Ingest transport: starts ingest
- Ingest transport → OTLP validation: validates signals
- Ingest transport → Signal sinks: dispatches records
- Signal sinks → Log store: writes logs
- Signal sinks → Metric store: writes metrics
- Signal sinks → Trace store: writes traces
- Metrics query API → Metric store: reads metrics
- Logs query API → Log store: reads logs
- Traces query API → Trace store: reads traces
- Analyst → Prism explorers: explores signals
- Prism explorers → Metrics query API: queries metrics
- Prism explorers → Logs query API: queries logs
- Prism explorers → Traces query API: queries traces
- Platform operator → Rule change control: plans rule changes
- Alert evaluation → Alert state: persists rule state