# sunnygeem/cold-start-hot-passion architecture

> Architecture diagram of the GitHub repository sunnygeem/cold-start-hot-passion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunnygeem/cold-start-hot-passion
- Repository: https://github.com/sunnygeem/cold-start-hot-passion

## Overview

This repository is a small eBPF-based observability prototype, split cleanly into a user-space Go loader and a kernel-space C program.

##### High-level architecture

There are three main layers:

1. **User-space control plane (`v1/main.go`)**
   - Written in **Go**.
   - Acts as the entrypoint for the tool.
   - Uses **cilium/ebpf** as the main runtime/library for loading and interacting with eBPF artifacts.
   - Responsible for starting the monitoring workflow, loading the compiled BPF program, and receiving data/events coming back from the kernel.

2. **Kernel-space data plane (`v1/monitor.c`)**
   - Written in **C** as an eBPF program.
   - Runs inside the Linux kernel context.
   - Implements the actual monitoring logic, likely by attaching to kernel hooks such as tracepoints, kprobes, or similar eBPF attachment points.
   - Produces telemetry or event records that are sent back to user space.

3. **Shared headers (`headers/`)**
   - `headers/common.h` contains shared data structures and constants used by both sides.
   - `headers/bpf_helpers.h` and `headers/bpf_helper_defs.h` provide the usual eBPF helper declarations and definitions needed to compile the kernel-side program.
   - This shared boundary is important: it keeps the user-space and kernel-space code aligned on event formats and constants.

##### Data flow

The dominant flow is:

- **Go application starts**
- **eBPF program is loaded into the kernel**
- **Kernel-side program observes an event source**
- **Kernel-side program emits records/events to user space**
- **Go code consumes and interprets those events**

So the architectural boundary is the standard eBPF split:
- **control and presentation in user space**
- **instrumentation and event generation in kernel space**

##### Repository structure and responsibilities

- `README.md`
  - Minimal project description and reference to `cilium/ebpf`.
  - Indicates this is a toy/learning project rather than a production system.

- `v1/`
  - Looks like a versioned implementation directory, suggesting this repo may evolve through multiple iterations.
  - `main.go` is the orchestrator.
  - `monitor.c` is the compiled eBPF component.

- `headers/`
  - Shared interface layer between Go and C.
  - Keeps ABI-like contracts stable across the language boundary.

##### Important architectural boundaries

1. **Go ↔ eBPF boundary**
   - The most important boundary in the system.
   - Go handles lifecycle, loading, and reading results.
   - C/eBPF handles execution in kernel context and must obey eBPF verifier constraints.

2. **Shared schema boundary**
   - `common.h` likely defines the event structure(s) exchanged between kernel and user space.
   - This is critical for diagramming because it is the contract that makes the two halves interoperable.

3. **Kernel execution boundary**
   - `monitor.c` runs under kernel restrictions, which means:
     - no general-purpose runtime
     - constrained memory usage
     - verifier-checked control flow
   - This shapes the design: the kernel side only collects and emits minimal structured data.

##### Technologies that materially affect the architecture

- **Go**: user-space orchestration and event consumption.
- **C/eBPF**: kernel-side instrumentation.
- **cilium/ebpf**: the library that bridges Go and eBPF program loading/interaction.
- **Linux kernel eBPF subsystem**: the runtime environment for `monitor.c`.

##### How to think about the diagram

A useful architecture diagram for this repo would show:

- A **Go user-space process** on one side.
- A **Linux kernel eBPF program** on the other side.
- A **shared headers/ABI layer** connecting the source code for both.
- A **data/event channel** from kernel back to Go.
- The **cilium/ebpf library** as the mechanism inside Go that loads and manages the BPF program.

This is not a multi-service system or a web application; it is a two-part monitoring pipeline with a strict user/kernel split.

Main entry points: [`v1/monitor.c`](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/v1/monitor.c) (Monitor), [`v1/main.go`](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/v1/main.go) (Main), [`headers/common.h`](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/headers/common.h) (Common), [`headers/bpf_helpers.h`](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/headers/bpf_helpers.h) (Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "User space"
  main["Main<br/>Go entrypoint<br/>[main.go]"]
  libebpf["cilium/ebpf<br/>Go library"]
end

subgraph "Kernel space"
  monitor["Monitor<br/>eBPF C program<br/>[monitor.c]"]
  kernel(("Linux kernel<br/>eBPF runtime"))
end

subgraph "Shared interface"
  common["Common<br/>shared structs<br/>[common.h]"]
  helpers["Helpers<br/>BPF headers<br/>[bpf_helpers.h]"]
  helper_defs["Helper defs<br/>BPF declarations<br/>[bpf_helper_defs.h]"]
end

main -->|"loads via"| libebpf
libebpf -->|"loads"| monitor
main -->|"uses schema"| common
monitor -->|"writes schema"| common
monitor -->|"includes"| helpers
monitor -->|"includes"| helper_defs
monitor -->|"runs in"| kernel
monitor -->|"events to"| main
main -.->|"controls"| kernel

click main "https://github.com/sunnygeem/cold-start-hot-passion/blob/main/v1/main.go"
click monitor "https://github.com/sunnygeem/cold-start-hot-passion/blob/main/v1/monitor.c"
click common "https://github.com/sunnygeem/cold-start-hot-passion/blob/main/headers/common.h"
click helpers "https://github.com/sunnygeem/cold-start-hot-passion/blob/main/headers/bpf_helpers.h"
click helper_defs "https://github.com/sunnygeem/cold-start-hot-passion/blob/main/headers/bpf_helper_defs.h"

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 main,libebpf toneBlue
class monitor,kernel toneAmber
class common,helpers,helper_defs toneMint
```

## Components

### User space

Go control plane and eBPF loader

- [Main](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/v1/main.go): Go entrypoint · Starts the monitoring workflow and consumes events · `v1/main.go`
- **cilium/ebpf**: Go library · Loads and manages the compiled eBPF program

### Kernel space

eBPF monitoring program

- [Monitor](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/v1/monitor.c): eBPF C program · Kernel-side instrumentation and event generation · `v1/monitor.c`
- **Linux kernel**: eBPF runtime · Verifier-checked execution environment for the monitoring program

### Shared interface

Headers and ABI contract

- [Common](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/headers/common.h): shared structs · Event formats and constants shared by Go and C · `headers/common.h`
- [Helpers](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/headers/bpf_helpers.h): BPF headers · eBPF helper declarations and definitions · `headers/bpf_helpers.h`
- [Helper defs](https://github.com/sunnygeem/cold-start-hot-passion/blob/HEAD/headers/bpf_helper_defs.h): BPF declarations · Low-level helper function definitions for BPF builds · `headers/bpf_helper_defs.h`

## Connections

- Main → cilium/ebpf: loads via · User-space process uses the eBPF library to load and attach programs
- cilium/ebpf → Monitor: loads · The Go runtime loads the compiled kernel program
- Main → Common: uses schema · User-space code interprets exchanged event records using shared types
- Monitor → Common: writes schema · Kernel program emits records matching the shared contract
- Monitor → Helpers: includes · Kernel program relies on standard eBPF helper declarations
- Monitor → Helper defs: includes · Kernel program uses helper definitions during compilation
- Monitor → Linux kernel: runs in · The eBPF program executes inside the Linux kernel
- Monitor → Main: events to · Telemetry and notifications flow back to the Go process
- Main → Linux kernel: controls · User-space loader manages kernel attachment lifecycle
