wind-rain/eunomia-bpf

<explanation>

1. Identify the project type and purpose

- This is an open‑source toolchain and runtime framework (eunomia-bpf) for building, distributing, and running eBPF programs.

- Key features (from README):

• A Rust/C library (bpf-loader-rs) to simplify writing and dynamically loading CO‑RE/libbpf eBPF programs

• A compiler toolchain (ecc in the compiler/ folder) to compile .bpf.c sources into JSON “config” or Wasm modules

• A CLI client (ecli/) to push, pull, run pre‑compiled eBPF programs as OCI images or from URLs

• SDK crates (eunomia-sdks/) for higher‑level languages (e.g., OpenTelemetry integration)

2. Analyze the file structure

- Top‑level crates and tools:

• bpf-loader-rs/: runtime library (Rust) plus a small CLI wrapper

• compiler/: the ecc compiler (Rust binary + Dockerfiles + templates)

• ecli/: the CLI client for registry operations and program execution

• eunomia-sdks/: language‑specific SDK crates (e.g., eunomia-otel)

- Patterns:

• Cargo workspace with multiple crates (libraries under src/, binaries under src/main.rs)

• examples/: dozens of .bpf.c test cases, demonstrating library usage

• documents/: a Docusaurus or mdBook‑style site describing architecture, usage, benchmarks

• CI/CD workflows in .github/workflows for building binaries, Docker images, docs

- Config & deployment artifacts:

• Dockerfiles for cross‑compilation (compiler/dockerfile*)

• GitHub Actions for release binaries, static builds, docs deploy

• JSON skeleton files (*.skel.json) as outputs of the compiler and inputs to the loader

3. Examine the README for additional insights

- The diagram should capture two main flows:

A. “Compile once” flow: .bpf.c + headers → ecc → Wasm module or JSON config

B. “Run everywhere” flow: CLI (ecli) pulls from URL/OCI → uses bpf-loader-rs → loads into kernel → exports events back to user space

- Dependencies: clang/llvm/libclang for compilation, libbpf at runtime, Wasm module loaders

4. How to create the system design diagram

a. Main components

1. Developer artifact (source code, .bpf.c, headers)

2. ecc compiler (binary + Docker image)

3. Output artifacts (JSON config, Wasm module, *.skel.json)

4. OCI Registry or HTTP host (GitHub Pages storage)

5. ecli client (pull, push, run)

6. bpf-loader-rs library & wrapper binary

7. Kernel BPF subsystem (CO‑RE + libbpf)

8. User‑space event handlers (perf event, ring buffer, JSON/plain text dumper)

9. SDKs (e.g., eunomia-otel) and custom applications

b. Relationships and interactions

- Arrow: source code → ecc → artifacts

- Arrow: artifacts → push to registry

- Arrow: ecli pull from registry → local cache

- Arrow: ecli (or custom app) calls bpf-loader-rs → interacts with kernel APIs

- Arrow: kernel programs emit events → bpf-loader-rs event handlers → CLI/SDK prints or forwards to telemetry back‑end

c. Architectural patterns and principles

- Modular monorepo with clear separation of compile‑time (ecc) vs. run‑time (bpf-loader-rs) concerns

- Plug‑in style event handlers under export_event in the Rust library

- CO‑RE portability plus Wasm layering for cross‑platform compatibility

- OCI‑based distribution for standardized packaging

d. Key technologies and frameworks

- Rust crates & Cargo workspaces

- libbpf and CO‑RE for kernel attachments

- LLVM/Clang toolchain for C→BPF compilation

- WebAssembly modules for alternative build outputs

- OCI registries, GitHub Actions, Docker for CI/CD and distribution

5. Guidelines for tailoring the diagram

- As an open‑source toolchain, emphasize:

• Core libraries (bpf-loader-rs, compiler internals)

• Extensibility points (export_event handlers, SDK consumer interfaces)

• Integration surfaces (OCI registry, Wasm ecosystem)

- Draw separate zones/layers:

• Developer (source & build)

• Distribution (registry, URL hosts)

• Runtime (client → loader → kernel → back to user space)

- Avoid UI/UX details—focus on programmatic flows and module boundaries

6. Diagram elements to include

- Labels: clear names for each box (e.g., “ecc compiler”, “ecli CLI”, “bpf-loader-rs”)

- Directional arrows: show data flow (source → compile → registry → run → kernel → user space)

- Color coding/shapes:

• Green boxes for compile‑time components

• Blue boxes for distribution (Registry/HTTP)

• Orange for runtime libraries & binaries

• Red or grey for kernel space

- Optionally, dashed borders to group related crates in the Cargo workspace

- A legend explaining colors and arrow styles

7. Detail and completeness

- Break down major Rust crates into “library vs. binary” where relevant

- Show test asset inputs under examples/ → feed into compiler

- Include CI/CD workflows only if relevant to deployment layer

- Call out the CO‑RE and Wasm build paths as parallel options

By following these steps and focusing on the flows above, you will produce a clear, accurate architecture diagram that highlights eunomia‑bpf’s compile and runtime framework, its modular crates, and its distribution strategy.

</explanation>