# cloudflare/foundations architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/foundations
- Repository: https://github.com/cloudflare/foundations

## Overview

##### Project Type and Purpose
- This is an open-source, modular Rust library (“Foundations”) for production-grade systems, providing logging, distributed tracing, metrics, memory profiling, seccomp-based sandboxing, configuration management, and a CLI helper.
- It consists of two main crates:
- foundations-macros: procedural macros to instrument user code (metrics, telemetry, settings helpers)
- foundations: core library implementing telemetry pipelines, security, configuration, CLI, etc.

##### High-Level Components
a. Application Layer (example or user service)
b. Macro Layer (foundations-macros)
c. Core Library Layer (foundations)
– Telemetry sub-system (logging, metrics, tracing, memory profiling)
– Security sub-system (seccomp syscall sandboxing)
– Configuration sub-system (YAML/CLI settings loader with docs)
– CLI helper
– Telemetry server (OTLP gRPC endpoint)
d. External Systems & Runtimes
– Logging sinks (files, stdout, dedicated backends)
– Metrics backends (Prometheus, StatsD, etc.)
– Tracing collectors (Jaeger, OTLP-gRPC)
– jemalloc allocator
– OS seccomp

##### Relationships and Data Flows
- Application code invokes macros (from foundations-macros) to declare metrics, tracing spans, config options.
- Macro expansion generates calls into the foundations core API.
- At runtime, the core API routes:
– Logs → log filters → log sinks (console, files, remote)
– Metrics → counters/gauges → push or pull exporters
– Traces → span builder → OTLP/Jaeger exporters
– Memory profiler → jemalloc hooks → profiling data
– Security: on startup, seccomp profiles loaded → kernel enforces syscall filters
– Configuration: CLI parser loads YAML → populates typed settings structs
- Telemetry server module can host an OTLP-gRPC endpoint to receive spans/metrics from remote services.

##### Architectural Patterns & Principles
– Layered design: macros → API surface → implementation modules → external integrations
– Separation of concerns: each sub-system (logging, metrics, tracing, security, config) lives in its own module hierarchy
– Extensibility: procedural macros generate hooks without user boilerplate; exporter backends pluggable via traits
– Runtime safety: seccomp sandboxing enforces least privilege

##### Detailed Capturing
- “(1) Macro invocations generate instrumentation calls.”
- Settings loader flow: CLI args + YAML → Settings struct → passed to other sub-systems.
- “Telemetry Server” as an optional HTTP/gRPC endpoint sidecar.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    UA["Example Application"]:::application
    UA -->|"(1) use macros"| Macros

    %% Macro Layer
    Macros["foundations-macros"]:::macros
    Macros -->|"generates"| API["foundations API Surface"]:::api

    %% Core Library Layer
    subgraph "foundations Core Library"
        direction TB
        API --> TelemetryCore
        API --> ConfigCore
        API --> SecurityCore
        API --> CLIHelper
        API --> TelemetryServer

        subgraph "Telemetry Sub-system"
            direction TB
            TelemetryCore["Telemetry Module"]:::telemetry
            TelemetryCore --> LoggingMod
            TelemetryCore --> MetricsMod
            TelemetryCore --> TracingMod
            TelemetryCore --> MemProf
            TelemetryCore --> OTLPConv
            TelemetryCore --> TokioMetrics
        end

        subgraph "Configuration Sub-system"
            direction TB
            ConfigCore["Config Module"]:::config
        end

        subgraph "Security Sub-system"
            direction TB
            SecurityCore["Security Module"]:::security
        end

        subgraph "CLI Helper"
            direction TB
            CLIHelper["CLI Helper"]:::api
        end

        subgraph "Telemetry Server"
            direction TB
            TelemetryServer["OTLP-gRPC Server"]:::telemetry
        end
    end

    %% Telemetry Modules
    LoggingMod["Logging Module"]:::telemetry
    MetricsMod["Metrics Module"]:::telemetry
    TracingMod["Tracing Module"]:::telemetry
    MemProf["Memory Profiler"]:::telemetry
    OTLPConv["OTLP Conversion"]:::telemetry
    TokioMetrics["Tokio Runtime Metrics"]:::telemetry

    %% External Systems
    subgraph "External Integrations"
        direction TB
        Logsinks["Log Sinks"]:::external
        MetricsBackends["Metrics Backends"]:::external
        TraceCollectors["Tracing Collectors"]:::external
        Jemalloc["jemalloc Profiler"]:::external
        SeccompSandbox["OS seccomp Sandbox"]:::external
    end

    LoggingMod -->|"routes logs"| Logsinks
    MetricsMod -->|"exports metrics"| MetricsBackends
    TracingMod -->|"exports spans"| TraceCollectors
    MemProf -->|"profiling data"| Jemalloc
    SecurityCore -->|"seccomp profiles"| SeccompSandbox

    %% Click Events - Macro Layer
    click Macros "https://github.com/cloudflare/foundations/tree/main/foundations-macros/"
    click Macros "https://github.com/cloudflare/foundations/blob/main/foundations-macros/src/lib.rs"
    click Macros "https://github.com/cloudflare/foundations/tree/main/foundations-macros/src/metrics/"
    click Macros "https://github.com/cloudflare/foundations/tree/main/foundations-macros/src/info_metric/"
    click Macros "https://github.com/cloudflare/foundations/blob/main/foundations-macros/src/settings.rs"
    click Macros "https://github.com/cloudflare/foundations/blob/main/foundations-macros/src/span_fn.rs"

    %% Click Events - Core Library
    click API "https://github.com/cloudflare/foundations/blob/main/foundations/src/lib.rs"
    click CLIHelper "https://github.com/cloudflare/foundations/blob/main/foundations/src/cli.rs"

    click TelemetryCore "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/"
    click TelemetryCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/telemetry/driver.rs"
    click LoggingMod "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/log/"
    click MetricsMod "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/metrics/"
    click TracingMod "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/tracing/"
    click MemProf "https://github.com/cloudflare/foundations/blob/main/foundations/src/telemetry/memory_profiler.rs"
    click OTLPConv "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/otlp_conversion/"
    click TokioMetrics "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/tokio_runtime_metrics/"
    click TelemetryServer "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/server/"
    click TelemetryCore "https://github.com/cloudflare/foundations/tree/main/foundations/src/telemetry/settings/"
    click TelemetryCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/telemetry/telemetry_context.rs"

    click SecurityCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/security/mod.rs"
    click SecurityCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/security/internal.rs"
    click SecurityCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/security/common_syscall_allow_lists.rs"
    click SecurityCore "https://github.com/cloudflare/foundations/tree/main/foundations/src/security/libseccomp/"
    click SecurityCore "https://github.com/cloudflare/foundations/tree/main/foundations/src/security/syscalls/"

    click ConfigCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/settings/mod.rs"
    click ConfigCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/settings/basic_impls.rs"
    click ConfigCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/settings/collections.rs"
    click ConfigCore "https://github.com/cloudflare/foundations/blob/main/foundations/src/settings/net.rs"
    click ConfigCore "https://github.com/cloudflare/foundations/tree/main/foundations/src/settings/"

    click UA "https://github.com/cloudflare/foundations/tree/main/examples/http_server/"
    click UA "https://github.com/cloudflare/foundations/blob/main/examples/http_server/main.rs"
    click UA "https://github.com/cloudflare/foundations/blob/main/examples/http_server/metrics.rs"
    click UA "https://github.com/cloudflare/foundations/blob/main/examples/http_server/settings.rs"
    click UA "https://github.com/cloudflare/foundations/blob/main/examples/http_server/example_conf.yaml"

    %% Styles
    classDef application fill:#EFEFFF,stroke:#0000CC,color:#0000CC;
    classDef macros fill:#FFF0E0,stroke:#CC6600,color:#CC6600;
    classDef api fill:#E0FFE0,stroke:#00AA00,color:#00AA00;
    classDef telemetry fill:#E0F0FF,stroke:#3366CC,color:#3366CC;
    classDef config fill:#E0FFE0,stroke:#33AA33,color:#33AA33;
    classDef security fill:#FFE0E0,stroke:#CC3333,color:#CC3333;
    classDef external fill:#EEEEEE,stroke:#888888,color:#555555;
```
