# plasma-umass/coz architecture

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

- Interactive diagram: https://gitdiagram.com/plasma-umass/coz
- Repository: https://github.com/plasma-umass/coz

## Overview

Coz instruments progress points in an application, samples execution, runs causal delay experiments, and writes profiles for inspection in the browser. The native runtime is the central implementation; language bindings expose progress-point APIs, while the viewer presents results and documents AI-assisted suggestions. The README also describes latency profiling and throughput profiling. Source excerpts show runtime initialization, profiler coordination, and progress-point interfaces; several platform and binding connections are inferred only at the product level and are marked unverified.

Main entry points: [`libcoz/profiler.cpp`](https://github.com/plasma-umass/coz/blob/master/libcoz/profiler.cpp) (Causal profiler), [`include/coz.h`](https://github.com/plasma-umass/coz/blob/master/include/coz.h) (Progress API), [`libcoz/inspect.cpp`](https://github.com/plasma-umass/coz/blob/master/libcoz/inspect.cpp) (Binary inspection), [`viewer/ts/profile.ts`](https://github.com/plasma-umass/coz/blob/master/viewer/ts/profile.ts) (Profile parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instrumentation["Instrumentation"]
  node_api["Progress API<br/>[coz.h]"]
end

subgraph group_runtime["Native runtime"]
  node_progress["Progress points<br/>[progress_point.h]"]
  node_bootstrap["Runtime bootstrap<br/>[libcoz.cpp]"]
  node_profiler["Causal profiler<br/>[profiler.cpp]"]
  node_samplers["Platform sampling<br/>[perf.cpp]"]
  node_macos_sampling["macOS sampling<br/>[perf_macos.cpp]"]
end

subgraph group_analysis["Profile analysis"]
  node_binary_inspection["Binary inspection<br/>[inspect.cpp]"]
  node_binary_loader["Binary loader<br/>[lief_loader.cpp]"]
  node_profile_output["Profile output<br/>[profiler.cpp]"]
end

subgraph group_viewer["Profile viewer"]
  node_viewer_parse["Profile parsing<br/>[profile.ts]"]
  node_viewer_ui["Interactive plots<br/>[ui.ts]"]
  node_ai_suggestions["AI suggestions"]
end

subgraph group_bindings["Language bindings"]
  node_go_binding["Go binding<br/>[coz.go]"]
  node_java_agent["Java agent<br/>[coz_agent.cpp]"]
  node_rust_binding["Rust binding<br/>[lib.rs]"]
  node_swift_binding["Swift binding<br/>[Coz.swift]"]
end

node_app(("Profiled program"))
node_llm_providers["LLM providers"]

node_app -->|"marks progress"| node_api
node_api -->|"records visits"| node_progress
node_bootstrap -->|"starts profiler"| node_profiler
node_profiler -->|"tracks points"| node_progress
node_profiler -->|"uses sampling"| node_samplers
node_profiler -->|"uses sampling"| node_macos_sampling
node_profiler -->|"maps samples"| node_binary_inspection
node_binary_inspection -->|"loads binaries"| node_binary_loader
node_profiler -->|"writes profile"| node_profile_output
node_profile_output -->|"opens profile"| node_viewer_parse
node_viewer_parse -.->|"supplies plots"| node_viewer_ui
node_viewer_ui -.->|"requests suggestions"| node_ai_suggestions
node_ai_suggestions -->|"uses providers"| node_llm_providers
node_go_binding -.->|"exposes progress API"| node_api
node_java_agent -.->|"exposes profiling"| node_api
node_rust_binding -.->|"exposes progress API"| node_api
node_swift_binding -.->|"exposes progress API"| node_api

click node_api "https://github.com/plasma-umass/coz/blob/master/include/coz.h"
click node_progress "https://github.com/plasma-umass/coz/blob/master/libcoz/progress_point.h"
click node_bootstrap "https://github.com/plasma-umass/coz/blob/master/libcoz/libcoz.cpp"
click node_profiler "https://github.com/plasma-umass/coz/blob/master/libcoz/profiler.cpp"
click node_samplers "https://github.com/plasma-umass/coz/blob/master/libcoz/perf.cpp"
click node_macos_sampling "https://github.com/plasma-umass/coz/blob/master/libcoz/perf_macos.cpp"
click node_binary_inspection "https://github.com/plasma-umass/coz/blob/master/libcoz/inspect.cpp"
click node_binary_loader "https://github.com/plasma-umass/coz/blob/master/libcoz/lief_loader.cpp"
click node_profile_output "https://github.com/plasma-umass/coz/blob/master/libcoz/profiler.cpp"
click node_viewer_parse "https://github.com/plasma-umass/coz/blob/master/viewer/ts/profile.ts"
click node_viewer_ui "https://github.com/plasma-umass/coz/blob/master/viewer/ts/ui.ts"
click node_ai_suggestions "https://github.com/plasma-umass/coz/tree/master/viewer"
click node_go_binding "https://github.com/plasma-umass/coz/blob/master/go/coz.go"
click node_java_agent "https://github.com/plasma-umass/coz/blob/master/java/agent/coz_agent.cpp"
click node_rust_binding "https://github.com/plasma-umass/coz/blob/master/rust/src/lib.rs"
click node_swift_binding "https://github.com/plasma-umass/coz/blob/master/swift/Sources/Coz/Coz.swift"

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 node_api toneBlue
class node_progress,node_bootstrap,node_profiler,node_samplers,node_macos_sampling toneAmber
class node_binary_inspection,node_binary_loader,node_profile_output toneMint
class node_viewer_parse,node_viewer_ui,node_ai_suggestions toneRose
class node_go_binding,node_java_agent,node_rust_binding,node_swift_binding,node_app,node_llm_providers toneIndigo
```

## Components

### Instrumentation

- [Progress API](https://github.com/plasma-umass/coz/blob/master/include/coz.h): `include/coz.h`

### Native runtime

- [Progress points](https://github.com/plasma-umass/coz/blob/master/libcoz/progress_point.h): `libcoz/progress_point.h`
- [Runtime bootstrap](https://github.com/plasma-umass/coz/blob/master/libcoz/libcoz.cpp): `libcoz/libcoz.cpp`
- [Causal profiler](https://github.com/plasma-umass/coz/blob/master/libcoz/profiler.cpp): `libcoz/profiler.cpp`
- [Platform sampling](https://github.com/plasma-umass/coz/blob/master/libcoz/perf.cpp): `libcoz/perf.cpp`
- [macOS sampling](https://github.com/plasma-umass/coz/blob/master/libcoz/perf_macos.cpp): `libcoz/perf_macos.cpp`

### Profile analysis

- [Binary inspection](https://github.com/plasma-umass/coz/blob/master/libcoz/inspect.cpp): `libcoz/inspect.cpp`
- [Binary loader](https://github.com/plasma-umass/coz/blob/master/libcoz/lief_loader.cpp): `libcoz/lief_loader.cpp`
- [Profile output](https://github.com/plasma-umass/coz/blob/master/libcoz/profiler.cpp): `libcoz/profiler.cpp`

### Profile viewer

- [Profile parsing](https://github.com/plasma-umass/coz/blob/master/viewer/ts/profile.ts): `viewer/ts/profile.ts`
- [Interactive plots](https://github.com/plasma-umass/coz/blob/master/viewer/ts/ui.ts): `viewer/ts/ui.ts`
- [AI suggestions](https://github.com/plasma-umass/coz/tree/master/viewer): `viewer`

### Language bindings

- [Go binding](https://github.com/plasma-umass/coz/blob/master/go/coz.go): `go/coz.go`
- [Java agent](https://github.com/plasma-umass/coz/blob/master/java/agent/coz_agent.cpp): `java/agent/coz_agent.cpp`
- [Rust binding](https://github.com/plasma-umass/coz/blob/master/rust/src/lib.rs): `rust/src/lib.rs`
- [Swift binding](https://github.com/plasma-umass/coz/blob/master/swift/Sources/Coz/Coz.swift): `swift/Sources/Coz/Coz.swift`

### Other components

- **Profiled program**
- **LLM providers**

## Connections

- Profiled program → Progress API: marks progress
- Progress API → Progress points: records visits (evidence: `libcoz/libcoz.cpp`)
- Runtime bootstrap → Causal profiler: starts profiler (evidence: `libcoz/libcoz.cpp`)
- Causal profiler → Progress points: tracks points (evidence: `libcoz/profiler.cpp`)
- Causal profiler → Platform sampling: uses sampling (evidence: `libcoz/profiler.cpp`)
- Causal profiler → macOS sampling: uses sampling (evidence: `libcoz/profiler.cpp`)
- Causal profiler → Binary inspection: maps samples (evidence: `libcoz/profiler.cpp`)
- Binary inspection → Binary loader: loads binaries (evidence: `libcoz/inspect.cpp`)
- Causal profiler → Profile output: writes profile (evidence: `libcoz/profiler.cpp`)
- Profile output → Profile parsing: opens profile
- Profile parsing → Interactive plots: supplies plots
- Interactive plots → AI suggestions: requests suggestions
- AI suggestions → LLM providers: uses providers
- Go binding → Progress API: exposes progress API
- Java agent → Progress API: exposes profiling
- Rust binding → Progress API: exposes progress API
- Swift binding → Progress API: exposes progress API
