# eclipse-score/inc_feo architecture

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

- Interactive diagram: https://gitdiagram.com/eclipse-score/inc_feo
- Repository: https://github.com/eclipse-score/inc_feo

## Overview

##### Project Type and Purpose
- This is a Rust‐centric, multi‐crate, Bazel/Cargo‐driven instrumentation and tracing library (“score‐feo”).
- It provides a core runtime (the `feo` crate) for event‐based Agents (primary/secondary/recorder), pluggable signalling layers (direct vs. relayed), recording backends, logging, time utilities, and integrations (Perfetto, external C++ libs).
- It also includes example applications (`cycle‐benchmark`, `mini‐adas`), a log‐demon (`logd`), and model crates (`perfetto-model`).

##### File Structure
- Top‐level build orchestrators:
- Bazel files: `BUILD.bazel`, `MODULE.bazel`, `.github/workflows/ci.yml`
- Docker: `docker/`
- Tools: `tools/format`
- Workspace crates (each under its own folder, each with `BUILD.bazel` and `Cargo.toml`):
- Core runtime: `feo/`
- Communication support: `feo-com/`
- C++ build macros: `feo-cpp-build/`, `feo-cpp-macros/`
- Logging: `feo-log/`, `feo-logger/`
- Timing: `feo-time/`
- Tracing frontends: `feo-tracer/`, `feo-tracing/`
- CLI server: `logd/`
- Protocol model: `perfetto-model/`
- Examples: `examples/rust/...` with Rust apps that link into the `feo` ecosystem.
- FFI/C++ integrations under `mini-adas/src/cpp` & headers.

##### Extract Insights from README
- Build/test with Bazel or Cargo.
- Examples demonstrate runtime usage (`bazel run //examples/rust/mini-adas:adas_primary`).
- Profiling using samply and bytehound points to performance‐sensitive design.

##### Components & Interactions
a. Main Components
1. Build System Layer
- Bazel (CI pipeline, workspace orchestration)
- Cargo (example builds)
2. Libraries Layer
- Core `feo` crate: defines Agent interfaces, scheduler, signalling abstractions, recording registry.
- `feo-com`: IPC channels (shmem, iox2).
- `feo-logger` / `feo-log`: Logging APIs and backends.
- `feo-time`: Timestamp and clock utilities.
- `feo-tracer` / `feo-tracing`: Tracing instrumentation and protocol support.
- `perfetto-model`: Protobuf definitions for Perfetto.
- `feo-cpp-build` / `feo-cpp-macros`: Facilitate C++ FFI.
3. Runtime Agents & Processes
- Primary agent (event producer)
- Recorder agent (aggregator/writer)
- Secondary agent (consumer/merger)
4. Signalling & Communication
- Direct in‐process (mpsc channels)
- Relayed across sockets or shared memory
5. Storage & Export
- In‐memory registry → disk via recorders
- `logd` daemon: RPC interface for client streams or packets
- Perfetto exporter (via `perfetto-model`)
6. Example Applications
- Rust cycle‐benchmark, mini‐adas (with C++ FFI)
- Linking paths into core crates
7. External Tools & Services
- Docker environment (for containerized runs)
- Profilers: samply, bytehound
- Browsers / Perfetto UI

b. Relationships and Data Flows
- Agents emit events → pass through Signalling layer → arrive at Recorder → persist or forward.
- `logd` connects to built‐in IPC exports or socket endpoints to receive/serve logs.
- FFI layer bridges Rust APIs to C++ components (`lane_assist.cpp`, `trajec_vis.cpp`) in mini‐adas.

c. Architectural Patterns & Principles
- Modular monorepo: each feature in its own crate
- Layered design:
- Interface (Agent, topicspec)
- Signalling (common, direct, relayed)
- Recording (registry, transcoder)
- Export (logd, perfetto)
- Pluggable backends (mpsc vs. shared memory vs. sockets)
- Zero‐cost abstractions in Rust (traits + generics)
- FFI isolation via dedicated crates

d. Key Technologies / Frameworks
- Rust toolchain (Cargo, clippy)
- Bazel + Bazelisk for large‐scale workspace management
- Tokio / async (implicit in signalling modules)
- Protobuf (perfetto‐model)
- C/C++ FFI via `bindgen`/`ffi.rs`
- IPC: Linux shared memory, iox2, UNIX sockets, mpsc channels

- Build dependencies (Bazel/Cargo → crates)
- Runtime data flow (Agent → Signalling → Recorder → logd/Perfetto)

##### Capturing Essential Elements
- Crates as modular components, grouped by functionality.
- Multi‐process topology (primary, secondary, recorder agents).
- External profiling and export services as side components.
- Don’t overcrowd: cluster similar crates (e.g., `feo-log` + `feo-logger`) but keep them distinct.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build System Layer
  subgraph "Build System Layer"
    direction TB
    Bazel["Bazel"]:::build
    BUILD["BUILD.bazel"]:::build
    MODULE["MODULE.bazel"]:::build
    CI[".github/workflows/ci.yml"]:::build
    Cargo["Cargo"]:::build
    CargoToml["Cargo.toml"]:::build
  end
  Bazel --> BUILD
  Bazel --> MODULE
  Bazel --> CI
  Cargo --> CargoToml

  %% Libraries Layer
  subgraph "Libraries Layer"
    direction TB
    feo["feo"]:::core
    feo_com["feo-com"]:::comm
    feo_cpp_build["feo-cpp-build"]:::cpp
    feo_cpp_macros["feo-cpp-macros"]:::cpp
    feo_log["feo-log"]:::log
    feo_logger["feo-logger"]:::log
    feo_time["feo-time"]:::time
    feo_tracer["feo-tracer"]:::tracing
    feo_tracing["feo-tracing"]:::tracing
    perfetto_model["perfetto-model"]:::model
  end
  Bazel --> feo
  Bazel --> feo_com
  Bazel --> feo_cpp_build
  Bazel --> feo_cpp_macros
  Bazel --> feo_log
  Bazel --> feo_logger
  Bazel --> feo_time
  Bazel --> feo_tracer
  Bazel --> feo_tracing
  Bazel --> perfetto_model

  %% Examples Layer
  subgraph "Example Applications"  
    direction TB
    cycle_bench["cycle-benchmark"]:::example
    mini_adas["mini-adas"]:::example
  end
  Cargo --> cycle_bench
  Cargo --> mini_adas
  cycle_bench --> feo
  cycle_bench --> feo_com
  mini_adas --> feo
  mini_adas --> feo_com
  mini_adas -.-> feo_cpp_build
  mini_adas -.-> feo_cpp_macros

  %% Runtime Agents
  subgraph "Runtime Agents"
    direction TB
    Primary["Primary Agent"]:::agent
    Recorder["Recorder Agent"]:::agent
    Secondary["Secondary Agent"]:::agent
  end

  %% Signalling & Communication
  subgraph "Signalling Layer"
    direction TB
    Direct["Direct (mpsc)"]:::comm
    Relayed["Relayed (shm/socket)"]:::comm
  end

  %% Recording Layer
  subgraph "Recording Layer"
    direction TB
    Registry["Registry"]:::record
    Transcoder["Transcoder"]:::record
  end

  %% Export Layer
  subgraph "Export & Daemon"
    direction TB
    Logd["logd (RPC)"]:::export
    PerfettoExp["Perfetto Exporter"]:::export
  end

  %% External Tools
  subgraph "External Tools"
    direction TB
    Docker["Docker"]:::external
    Profilers["Samply/Bytehound"]:::external
    Browser["Perfetto UI"]:::external
  end

  %% Runtime Flows
  Primary -->|"emit events"| Direct
  Primary -->|"emit events"| Relayed
  Secondary -->|"consume events"| Direct
  Secondary -->|"consume events"| Relayed
  Direct -->|"transport"| Registry
  Relayed -->|"transport"| Registry
  Registry -->|"transcode"| Transcoder
  Transcoder -->|"persist"| Recorder
  Recorder -->|"serve"| Logd
  Transcoder -->|"export"| PerfettoExp
  Logd -->|"stream logs"| Browser

  %% External Connections
  Docker --> Bazel
  Docker --> Cargo
  Profilers --> Primary
  Profilers --> Secondary

  %% Click Events
  click BUILD "https://github.com/eclipse-score/inc_feo/blob/main//BUILD.bazel"
  click MODULE "https://github.com/eclipse-score/inc_feo/blob/main//MODULE.bazel"
  click CI "https://github.com/eclipse-score/inc_feo/blob/main//.github/workflows/ci.yml"
  click CargoToml "https://github.com/eclipse-score/inc_feo/blob/main//Cargo.toml"
  click feo "https://github.com/eclipse-score/inc_feo/blob/main/feo/Cargo.toml"
  click feo_com "https://github.com/eclipse-score/inc_feo/blob/main/feo-com/Cargo.toml"
  click feo_cpp_build "https://github.com/eclipse-score/inc_feo/blob/main/feo-cpp-build/Cargo.toml"
  click feo_cpp_macros "https://github.com/eclipse-score/inc_feo/blob/main/feo-cpp-macros/Cargo.toml"
  click feo_log "https://github.com/eclipse-score/inc_feo/blob/main/feo-log/Cargo.toml"
  click feo_logger "https://github.com/eclipse-score/inc_feo/blob/main/feo-logger/Cargo.toml"
  click feo_time "https://github.com/eclipse-score/inc_feo/blob/main/feo-time/Cargo.toml"
  click feo_tracer "https://github.com/eclipse-score/inc_feo/blob/main/feo-tracer/Cargo.toml"
  click feo_tracing "https://github.com/eclipse-score/inc_feo/blob/main/feo-tracing/Cargo.toml"
  click perfetto_model "https://github.com/eclipse-score/inc_feo/blob/main/perfetto-model/Cargo.toml"
  click cycle_bench "https://github.com/eclipse-score/inc_feo/blob/main/examples/rust/cycle-benchmark/Cargo.toml"
  click mini_adas "https://github.com/eclipse-score/inc_feo/blob/main/examples/rust/mini-adas/Cargo.toml"
  click feo "https://github.com/eclipse-score/inc_feo/blob/main/feo/src/lib.rs"
  click feo "https://github.com/eclipse-score/inc_feo/tree/main//feo/src/agent"
  click feo "https://github.com/eclipse-score/inc_feo/tree/main//feo/src/signalling"
  click feo "https://github.com/eclipse-score/inc_feo/tree/main//feo/src/recording"
  click feo "https://github.com/eclipse-score/inc_feo/blob/main//feo/src/scheduler.rs"
  click feo_com "https://github.com/eclipse-score/inc_feo/blob/main//feo-com/src/interface.rs"
  click feo_com "https://github.com/eclipse-score/inc_feo/tree/main//feo-com/src/iox2"
  click feo_com "https://github.com/eclipse-score/inc_feo/tree/main//feo-com/src/linux_shm"
  click feo_cpp_build "https://github.com/eclipse-score/inc_feo/blob/main//feo-cpp-build/src/include/feo_cpp/feo_macros.h"
  click feo_cpp_macros "https://github.com/eclipse-score/inc_feo/blob/main//feo-cpp-macros/src/lib.rs"
  click feo_log "https://github.com/eclipse-score/inc_feo/blob/main//feo-log/src/lib.rs"
  click feo_log "https://github.com/eclipse-score/inc_feo/blob/main//feo-log/src/log.cc"
  click feo_log "https://github.com/eclipse-score/inc_feo/blob/main//feo-log/include/log.h"
  click feo_logger "https://github.com/eclipse-score/inc_feo/blob/main//feo-logger/src/console.rs"
  click feo_logger "https://github.com/eclipse-score/inc_feo/blob/main//feo-logger/src/logd.rs"
  click feo_logger "https://github.com/eclipse-score/inc_feo/blob/main//feo-logger/include/logger.h"
  click feo_time "https://github.com/eclipse-score/inc_feo/blob/main//feo-time/src/lib.rs"
  click feo_time "https://github.com/eclipse-score/inc_feo/blob/main//feo-time/include/feo_time.h"
  click feo_tracer "https://github.com/eclipse-score/inc_feo/blob/main//feo-tracer/src/lib.rs"
  click feo_tracer "https://github.com/eclipse-score/inc_feo/blob/main//feo-tracer/src/perfetto.rs"
  click feo_tracing "https://github.com/eclipse-score/inc_feo/blob/main//feo-tracing/src/protocol.rs"
  click feo_tracing "https://github.com/eclipse-score/inc_feo/blob/main//feo-tracing/src/subscriber.rs"
  click perfetto_model "https://github.com/eclipse-score/inc_feo/blob/main//perfetto-model/protos/perfetto_trace.proto"
  click cycle_bench "https://github.com/eclipse-score/inc_feo/blob/main//examples/rust/cycle-benchmark/src/bin/cycle_bench.rs"
  click mini_adas "https://github.com/eclipse-score/inc_feo/blob/main//examples/rust/mini-adas/src/bin/adas_primary.rs"
  click mini_adas "https://github.com/eclipse-score/inc_feo/blob/main//examples/rust/mini-adas/src/ffi.rs"
  click mini_adas "https://github.com/eclipse-score/inc_feo/blob/main//examples/rust/mini-adas/src/cpp/lane_assist.cpp"
  click mini_adas "https://github.com/eclipse-score/inc_feo/blob/main//examples/rust/mini-adas/src/include/lane_assist.h"

  %% Styles
  classDef build fill:#DDA0DD,stroke:#333,stroke-width:1px;
  classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
  classDef comm fill:#90EE90,stroke:#333,stroke-width:1px;
  classDef cpp fill:#D3D3D3,stroke:#333,stroke-width:1px;
  classDef log fill:#FFDAB9,stroke:#333,stroke-width:1px;
  classDef time fill:#E0FFFF,stroke:#333,stroke-width:1px;
  classDef tracing fill:#E6E6FA,stroke:#333,stroke-width:1px;
  classDef model fill:#F0E68C,stroke:#333,stroke-width:1px;
  classDef example fill:#FFD700,stroke:#333,stroke-width:1px;
  classDef agent fill:#FFB6C1,stroke:#333,stroke-width:1px;
  classDef record fill:#FFA500,stroke:#333,stroke-width:1px;
  classDef export fill:#FA8072,stroke:#333,stroke-width:1px;
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
