# facebookincubator/below architecture

> Architecture diagram of the GitHub repository facebookincubator/below, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookincubator/below
- Repository: https://github.com/facebookincubator/below

## Overview

##### Project type & purpose
- This is a Rust-based, CLI-driven system-monitoring tool ("below") that supports live viewing, recording, replaying, dumping, and snapshotting of Linux system data (cgroups, fs stats, PSI, etc.).
- It’s organized as a Cargo workspace with one top-level binary crate (“below”) plus ~12 library crates (e.g., `btrfs`, `cgroupfs`, `model`, `store`, `view`, `dump`, `render`, etc.) supplying plugins, data models, storage, UI, and exporters.

##### High-level layers
a.  CLI & orchestration (binary crate under `src/main.rs`)
b.  Data collection plugins (crates: `btrfs`, `cgroupfs`, `procfs`, `ethtool`, `resctrlfs`, `tc`, `gpu_stats`, plus BPF code in `src/bpf`)
c.  Core abstractions & model (crates: `common`, `model`, `config`)
d.  Storage & export (crates: `store`, `dump`)
e.  Rendering & interactive UI (crates: `render`, `view`)

##### Inter-component flows
- “below live”:
–  CLI invokes plugin collectors → raw samples → `model` transforms → `view` (TUI) or `render` (default configs)
- “below record”:
–  collectors → `model` → `store` persists (CBOR or remote via `store::open_source::remote_store`)
–  service unit (`etc/below.service`) & systemd/OpenRC integration
- “below replay”:
–  `store` reads historical data → `model` → `view`/`render`
- “below dump”:
–  collectors → `model` → `dump` formats to JSON/CSV/OpenMetrics → external tools (Prometheus scrape → Grafana dashboards in `contrib/grafana`)
- Configuration:
–  `config` crate loads CLI flags / config file (`docs/belowrc.md`) → influences collector parameters, view filters, dump formats.

##### Architectural patterns & principles
- Modular crates-per-responsibility: each subsystem (fs, cgroup, network, GPU, BPF) lives in its own library crate.
- Plugin-style collector interfaces: dynamic dispatch over common traits in `common` and `model`.
- Clear separation of concerns (MVC-ish):
–  Model = `model` crate
–  View = `view` + `render` crates
–  Controller = CLI command dispatcher in `src/main.rs`
- Single event loop per command (live/replay) feeding data through a channel to the UI or store.
- Use of derive macros (`below_derive`) to reduce boilerplate in plugin implementations.

##### Elements
- Clear labels: crate names & responsibilities (e.g., “model: unifies sample representation”).
–  Blue = live/replay pipeline
–  Green = record pipeline
–  Orange = dump/export pipeline
–  Solid for in-process crates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Controller Layer
    subgraph "Controller"
        CLI["below\n(src/main.rs)"]:::controller
    end

    %% Configuration Layer
    subgraph "Configuration"
        Config["config\n(src/lib.rs)"]:::config
        Docs["belowrc.md"]:::config
    end

    %% Utilities Layer
    subgraph "Utilities"
        Common["common\n(src/lib.rs)"]:::common
        Derive["below_derive\n(src/lib.rs)"]:::derive
    end

    %% Collectors Layer
    subgraph "Collectors"
        Btrfs["btrfs"]:::plugin
        Cgroupfs["cgroupfs"]:::plugin
        Procfs["procfs"]:::plugin
        Ethtool["ethtool"]:::plugin
        Resctrlfs["resctrlfs"]:::plugin
        Tc["tc"]:::plugin
        GPU["gpu_stats"]:::plugin
        BPFc["BPF Collectors"]:::plugin
    end

    %% Core Model Layer
    subgraph "Core Model"
        Model["model"]:::model
    end

    %% Storage Layer
    subgraph "Storage"
        Store["store"]:::storage
        Remote["remote_store"]:::storage
    end

    %% Export Layer
    subgraph "Export (Dump)"
        Dump["dump"]:::export
    end

    %% Rendering & UI Layer
    subgraph "Rendering & UI"
        Render["render"]:::render
        View["view (TUI)"]:::view
    end

    %% Deployment / Packaging
    subgraph "Deployment / Packaging"
        Docker["Dockerfile"]:::deployment
        Service["below.service"]:::deployment
        GrafanaDep["contrib/grafana"]:::deployment
    end

    %% External Systems
    subgraph "External Interfaces"
        Kernel["Linux Kernel\n(sysfs/procfs/BPF)"]:::external
        Systemd["systemd/OpenRC"]:::external
        Prom["Prometheus"]:::external
        GrafExt["Grafana Dashboards"]:::external
    end

    %% Relationships - CLI setup
    CLI -->|"loads config"| Config
    CLI -->|"uses common traits"| Common
    CLI -->|"invokes derive macros"| Derive
    CLI -->|"dispatches commands"| Btrfs
    CLI --> Btrfs
    CLI --> Cgroupfs
    CLI --> Procfs
    CLI --> Ethtool
    CLI --> Resctrlfs
    CLI --> Tc
    CLI --> GPU
    CLI --> BPFc

    %% Plugin to Model
    Btrfs -->|blue: live/replay<br>green: record<br>orange: dump| Model
    Cgroupfs --> Model
    Procfs --> Model
    Ethtool --> Model
    Resctrlfs --> Model
    Tc --> Model
    GPU --> Model
    BPFc --> Model

    %% Model to downstream
    Model -->|"blue: live/replay"| View
    Model -->|"blue: live/replay"| Render
    Model -->|"green: record"| Store
    Store -->|"write CBOR→ disk"| Disk[Disk Storage]:::storage
    Store -->|"green: remote"| Remote
    Model -->|"orange: dump"| Dump
    Dump -->|"export JSON/CSV→ stdout"| Stdout[Stdout]:::export
    Dump -->|"Prometheus scrape"| Prom
    Dump -->|"Grafana dashboards"| GrafExt

    %% External integrations
    BPFc --> Kernel
    Config --> Docs
    Service --> Systemd
    Dump --> GrafExt

    %% Deployment links
    Docker --- CLI
    Docker --- Service
    GrafanaDep --- GrafExt

    %% Click Events
    click CLI "https://github.com/facebookincubator/below/blob/main/below/src/main.rs"
    click Config "https://github.com/facebookincubator/below/blob/main/below/config/src/lib.rs"
    click Docs "https://github.com/facebookincubator/below/blob/main/docs/belowrc.md"
    click Common "https://github.com/facebookincubator/below/blob/main/below/common/src/lib.rs"
    click Derive "https://github.com/facebookincubator/below/blob/main/below/below_derive/src/lib.rs"
    click Btrfs "https://github.com/facebookincubator/below/blob/main/below/btrfs/src/lib.rs"
    click Cgroupfs "https://github.com/facebookincubator/below/blob/main/below/cgroupfs/src/lib.rs"
    click Procfs "https://github.com/facebookincubator/below/blob/main/below/procfs/src/lib.rs"
    click Ethtool "https://github.com/facebookincubator/below/blob/main/below/ethtool/src/lib.rs"
    click Resctrlfs "https://github.com/facebookincubator/below/blob/main/below/resctrlfs/src/lib.rs"
    click Tc "https://github.com/facebookincubator/below/blob/main/below/tc/src/lib.rs"
    click GPU "https://github.com/facebookincubator/below/blob/main/below/gpu_stats/src/lib.rs"
    click BPFc "https://github.com/facebookincubator/below/blob/main/below/src/bpf/exitstat.bpf.c"
    click Model "https://github.com/facebookincubator/below/blob/main/below/model/src/lib.rs"
    click Store "https://github.com/facebookincubator/below/blob/main/below/store/src/lib.rs"
    click Remote "https://github.com/facebookincubator/below/blob/main/below/store/src/open_source/remote_store.rs"
    click Dump "https://github.com/facebookincubator/below/blob/main/below/dump/src/lib.rs"
    click Render "https://github.com/facebookincubator/below/blob/main/below/render/src/lib.rs"
    click View "https://github.com/facebookincubator/below/blob/main/below/view/src/lib.rs"
    click Docker "https://github.com/facebookincubator/below/tree/main/Dockerfile"
    click Service "https://github.com/facebookincubator/below/blob/main/etc/below.service"
    click GrafanaDep "https://github.com/facebookincubator/below/tree/main/contrib/grafana/"

    %% Styles
    classDef controller fill:#cce5ff,stroke:#333;
    classDef config fill:#fff3cd,stroke:#333;
    classDef common fill:#e2e3e5,stroke:#333;
    classDef derive fill:#f8d7da,stroke:#333;
    classDef plugin fill:#d4edda,stroke:#333;
    classDef model fill:#f5c6cb,stroke:#333;
    classDef storage fill:#d1ecf1,stroke:#333;
    classDef export fill:#ffe5b4,stroke:#333;
    classDef render fill:#d1ecf1,stroke:#333;
    classDef view fill:#d1ecf1,stroke:#333;
    classDef deployment fill:#faf2cc,stroke:#333;
    classDef external fill:#f0f0f0,stroke:#333,stroke-dasharray: 5 5;
```
