# tanelpoder/0xtools architecture

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

- Interactive diagram: https://gitdiagram.com/tanelpoder/0xtools
- Repository: https://github.com/tanelpoder/0xtools

## Overview

xCapture captures Linux thread activity through eBPF sampling and optional syscall/I/O tracking, then emits terminal output or CSV datasets. xtop consumes those datasets for DuckDB-backed dimensional queries and interactive terminal analysis, including latency histograms, heatmaps, and cell details. The graph preserves these distinct capture and analysis stages. Several probe and TUI implementations are unsampled, so their roles are represented from documented capabilities and the tree, with unverified links marked dashed.

Main entry points: [`xcapture/src/user/main.c`](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/main.c) (Sampling driver), [`xtop/tui/cell_peek_modal.py`](https://github.com/tanelpoder/0xtools/blob/master/xtop/tui/cell_peek_modal.py) (Cell detail views), [`xtop/core/query_engine.py`](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/query_engine.py) (Query engine), [`xcapture/src/user/task_handler.c`](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/task_handler.c) (Sample handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["xCapture capture"]
  node_driver["Sampling driver<br/>[main.c]"]
  node_taskprobe["Task sampler<br/>[task.bpf.c]"]
  node_sysprobe["Syscall tracking<br/>[syscall.bpf.c]"]
  node_ioprobe["I/O tracking<br/>[iorq_hashmap.bpf.c]"]
  node_taskhandler["Sample handling<br/>[task_handler.c]"]
  node_trackhandler["Tracking handling<br/>[tracking_handler.c]"]
  node_csv["CSV output<br/>[output_writer.c]"]
  node_stdout["Terminal output<br/>[columns.c]"]
end

subgraph group_analysis["xtop analysis"]
  node_xtopdata["CSV data source<br/>[data_source.py]"]
  node_engine["Query engine<br/>[query_engine.py]"]
  node_builder["SQL query builder<br/>[query_builder.py]"]
  node_timefilter["Time filtering<br/>[csv_time_filter.py]"]
  node_heatmap["Heatmap analysis<br/>[heatmap.py]"]
  node_timeutils["Time utilities<br/>[time_utils.py]"]
end

subgraph group_presentation["Interactive presentation"]
  node_tui["xtop terminal UI<br/>[cell_peek_modal.py]"]
  node_peek["Cell detail views<br/>[cell_peek_modal.py]"]
  node_heatvisual["Heatmap rendering"]
  node_histogram["Histogram formatting"]
end

node_operator(("Operator"))
node_datasets[("Capture datasets")]
node_duckdb[("DuckDB")]

node_operator -->|"starts"| node_driver
node_driver -->|"drives sampling"| node_taskprobe
node_sysprobe -.->|"emits events"| node_trackhandler
node_ioprobe -.->|"emits events"| node_trackhandler
node_taskprobe -.->|"emits samples"| node_taskhandler
node_driver -.->|"handles samples"| node_taskhandler
node_driver -.->|"handles tracking"| node_trackhandler
node_taskhandler -.->|"writes records"| node_csv
node_trackhandler -->|"writes records"| node_csv
node_taskhandler -->|"formats output"| node_stdout
node_driver -->|"prints results"| node_stdout
node_csv -->|"appends samples"| node_datasets
node_datasets -->|"reads CSV"| node_xtopdata
node_xtopdata -->|"uses time filter"| node_timefilter
node_engine -->|"connects to"| node_xtopdata
node_engine -->|"builds queries"| node_builder
node_engine -->|"executes SQL"| node_duckdb
node_operator -->|"analyzes data"| node_tui
node_tui -.->|"queries data"| node_engine
node_peek -->|"uses analysis"| node_heatmap
node_peek -->|"renders heatmap"| node_heatvisual
node_peek -->|"formats histogram"| node_histogram
node_peek -->|"uses time helpers"| node_timeutils

click node_driver "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/main.c"
click node_taskprobe "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/task/task.bpf.c"
click node_sysprobe "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/syscall/syscall.bpf.c"
click node_ioprobe "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/io/iorq_hashmap.bpf.c"
click node_taskhandler "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/task_handler.c"
click node_trackhandler "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/tracking_handler.c"
click node_csv "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/output_writer.c"
click node_stdout "https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/columns.c"
click node_xtopdata "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/data_source.py"
click node_engine "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/query_engine.py"
click node_builder "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/query_builder.py"
click node_timefilter "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/csv_time_filter.py"
click node_tui "https://github.com/tanelpoder/0xtools/blob/master/xtop/tui/cell_peek_modal.py"
click node_peek "https://github.com/tanelpoder/0xtools/blob/master/xtop/tui/cell_peek_modal.py"
click node_heatmap "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/heatmap.py"
click node_heatvisual "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/heatmap_visualizer.py"
click node_histogram "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/histogram_formatter.py"
click node_timeutils "https://github.com/tanelpoder/0xtools/blob/master/xtop/core/time_utils.py"

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_driver,node_taskprobe,node_sysprobe,node_ioprobe,node_taskhandler,node_trackhandler,node_csv,node_stdout toneBlue
class node_xtopdata,node_engine,node_builder,node_timefilter,node_heatmap,node_timeutils,node_datasets,node_duckdb toneAmber
class node_tui,node_peek,node_heatvisual,node_histogram toneMint
class node_operator toneIndigo
```

## Components

### xCapture capture

- [Sampling driver](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/main.c): `xcapture/src/user/main.c`
- [Task sampler](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/task/task.bpf.c): `xcapture/src/probes/task/task.bpf.c`
- [Syscall tracking](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/syscall/syscall.bpf.c): `xcapture/src/probes/syscall/syscall.bpf.c`
- [I/O tracking](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/probes/io/iorq_hashmap.bpf.c): `xcapture/src/probes/io/iorq_hashmap.bpf.c`
- [Sample handling](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/task_handler.c): `xcapture/src/user/task_handler.c`
- [Tracking handling](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/tracking_handler.c): `xcapture/src/user/tracking_handler.c`
- [CSV output](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/output_writer.c): `xcapture/src/user/output_writer.c`
- [Terminal output](https://github.com/tanelpoder/0xtools/blob/master/xcapture/src/user/columns.c): `xcapture/src/user/columns.c`

### xtop analysis

- [CSV data source](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/data_source.py): `xtop/core/data_source.py`
- [Query engine](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/query_engine.py): `xtop/core/query_engine.py`
- [SQL query builder](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/query_builder.py): `xtop/core/query_builder.py`
- [Time filtering](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/csv_time_filter.py): `xtop/core/csv_time_filter.py`
- [Heatmap analysis](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/heatmap.py): `xtop/core/heatmap.py`
- [Time utilities](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/time_utils.py): `xtop/core/time_utils.py`

### Interactive presentation

- [xtop terminal UI](https://github.com/tanelpoder/0xtools/blob/master/xtop/tui/cell_peek_modal.py): `xtop/tui/cell_peek_modal.py`
- [Cell detail views](https://github.com/tanelpoder/0xtools/blob/master/xtop/tui/cell_peek_modal.py): `xtop/tui/cell_peek_modal.py`
- [Heatmap rendering](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/heatmap_visualizer.py): `xtop/core/heatmap_visualizer.py`
- [Histogram formatting](https://github.com/tanelpoder/0xtools/blob/master/xtop/core/histogram_formatter.py): `xtop/core/histogram_formatter.py`

### Other components

- **Operator**
- **Capture datasets**
- **DuckDB**

## Connections

- Operator → Sampling driver: starts
- Sampling driver → Task sampler: drives sampling
- Syscall tracking → Tracking handling: emits events
- I/O tracking → Tracking handling: emits events
- Task sampler → Sample handling: emits samples
- Sampling driver → Sample handling: handles samples
- Sampling driver → Tracking handling: handles tracking
- Sample handling → CSV output: writes records
- Tracking handling → CSV output: writes records (evidence: `xcapture/src/user/tracking_handler.c`)
- Sample handling → Terminal output: formats output (evidence: `xcapture/src/user/task_handler.c`)
- Sampling driver → Terminal output: prints results
- CSV output → Capture datasets: appends samples
- Capture datasets → CSV data source: reads CSV
- CSV data source → Time filtering: uses time filter (evidence: `xtop/core/data_source.py`)
- Query engine → CSV data source: connects to (evidence: `xtop/core/query_engine.py`)
- Query engine → SQL query builder: builds queries (evidence: `xtop/core/query_engine.py`)
- Query engine → DuckDB: executes SQL (evidence: `xtop/core/query_engine.py`)
- Operator → xtop terminal UI: analyzes data
- xtop terminal UI → Query engine: queries data
- Cell detail views → Heatmap analysis: uses analysis (evidence: `xtop/tui/cell_peek_modal.py`)
- Cell detail views → Heatmap rendering: renders heatmap (evidence: `xtop/tui/cell_peek_modal.py`)
- Cell detail views → Histogram formatting: formats histogram (evidence: `xtop/tui/cell_peek_modal.py`)
- Cell detail views → Time utilities: uses time helpers (evidence: `xtop/tui/cell_peek_modal.py`)
