# pigweed-project/pigweed architecture

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

- Interactive diagram: https://gitdiagram.com/pigweed-project/pigweed
- Repository: https://github.com/pigweed-project/pigweed

## Overview

Pigweed is a collection of embedded-targeted C++ and other-language modules, not one application with a single end-to-end runtime. An engineer selects modules to build firmware or supporting services; the resulting behavior depends on that selection. The map highlights major library domains and the RPC query workflow visible in sampled sources. Most module interactions are intentionally not connected because the available evidence does not establish calls between them; the repository-wide capability map is necessarily selective.

Main entry points: [`pw_rpc/public/pw_rpc/server.h`](https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/public/pw_rpc/server.h) (RPC server), [`pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc`](https://github.com/pigweed-project/pigweed/blob/main/pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc) (Bluetooth proxy), [`pw_status/public/pw_status/status.h`](https://github.com/pigweed-project/pigweed/blob/main/pw_status/public/pw_status/status.h) (Status), [`pw_rpc/pwpb/query_service.cc`](https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/pwpb/query_service.cc) (RPC query service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_primitives["Core primitives"]
  node_preprocessor["Preprocessor<br/>[compiler.h]"]
  node_span["Span<br/>[span.h]"]
  node_status["Status<br/>[status.h]"]
  node_result["Result<br/>[result.h]"]
  node_containers["Containers<br/>[vector.h]"]
end

subgraph group_runtime["Runtime and concurrency"]
  node_async2["Async tasks<br/>[task.h]"]
  node_futures["Futures<br/>[future.h]"]
  node_sync["Synchronization<br/>[lock_annotations.h]"]
end

subgraph group_memory["Memory and storage"]
  node_allocator["Allocators<br/>[allocator.h]"]
  node_deallocator["Deallocation<br/>[deallocator.h]"]
  node_blobstore["Blob store<br/>[blob_store.cc]"]
end

subgraph group_communications["Communications"]
  node_rpcserver["RPC server<br/>[server.h]"]
  node_queryservice["RPC query service<br/>[query_service.cc]"]
  node_transfer["Data transfer<br/>[client_context.cc]"]
  node_bluetooth["Bluetooth APIs<br/>[emboss_util.h]"]
  node_btproxy["Bluetooth proxy"]
end

subgraph group_diagnostics["Diagnostics"]
  node_assertions["Assertions<br/>[assert.h]"]
  node_checks["Checks<br/>[check.h]"]
  node_logging["Logging<br/>[log.h]"]
end

node_engineer(("Firmware engineer"))

node_engineer -.->|"selects modules"| node_allocator
node_engineer -.->|"selects modules"| node_async2
node_engineer -.->|"selects modules"| node_rpcserver
node_engineer -.->|"selects modules"| node_bluetooth
node_rpcserver -->|"uses lists"| node_containers
node_rpcserver -->|"uses spans"| node_span
node_rpcserver -->|"uses status"| node_status
node_queryservice -->|"registers and queries"| node_rpcserver
node_queryservice -->|"returns status"| node_status
node_btproxy -->|"uses packet utilities"| node_bluetooth
node_btproxy -->|"checks conditions"| node_assertions
node_btproxy -->|"logs events"| node_logging
node_futures -.->|"uses status"| node_status
node_transfer -.->|"uses RPC"| node_rpcserver

click node_preprocessor "https://github.com/pigweed-project/pigweed/blob/main/pw_preprocessor/public/pw_preprocessor/compiler.h"
click node_span "https://github.com/pigweed-project/pigweed/blob/main/pw_span/public/pw_span/span.h"
click node_status "https://github.com/pigweed-project/pigweed/blob/main/pw_status/public/pw_status/status.h"
click node_result "https://github.com/pigweed-project/pigweed/blob/main/pw_result/public/pw_result/result.h"
click node_containers "https://github.com/pigweed-project/pigweed/blob/main/pw_containers/public/pw_containers/vector.h"
click node_allocator "https://github.com/pigweed-project/pigweed/blob/main/pw_allocator/public/pw_allocator/allocator.h"
click node_deallocator "https://github.com/pigweed-project/pigweed/blob/main/pw_allocator/public/pw_allocator/deallocator.h"
click node_blobstore "https://github.com/pigweed-project/pigweed/blob/main/pw_blob_store/blob_store.cc"
click node_async2 "https://github.com/pigweed-project/pigweed/blob/main/pw_async2/public/pw_async2/task.h"
click node_futures "https://github.com/pigweed-project/pigweed/blob/main/pw_async2/public/pw_async2/future.h"
click node_sync "https://github.com/pigweed-project/pigweed/blob/main/pw_sync/public/pw_sync/lock_annotations.h"
click node_rpcserver "https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/public/pw_rpc/server.h"
click node_queryservice "https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/pwpb/query_service.cc"
click node_transfer "https://github.com/pigweed-project/pigweed/blob/main/pw_transfer/client_context.cc"
click node_bluetooth "https://github.com/pigweed-project/pigweed/blob/main/pw_bluetooth/public/pw_bluetooth/emboss_util.h"
click node_btproxy "https://github.com/pigweed-project/pigweed/blob/main/pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc"
click node_assertions "https://github.com/pigweed-project/pigweed/blob/main/pw_assert/public/pw_assert/assert.h"
click node_checks "https://github.com/pigweed-project/pigweed/blob/main/pw_assert/public/pw_assert/check.h"
click node_logging "https://github.com/pigweed-project/pigweed/blob/main/pw_log/public/pw_log/log.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 node_preprocessor,node_span,node_status,node_result,node_containers toneBlue
class node_async2,node_futures,node_sync toneAmber
class node_allocator,node_deallocator,node_blobstore toneMint
class node_rpcserver,node_queryservice,node_transfer,node_bluetooth,node_btproxy toneRose
class node_assertions,node_checks,node_logging,node_engineer toneIndigo
```

## Components

### Core primitives

- [Preprocessor](https://github.com/pigweed-project/pigweed/blob/main/pw_preprocessor/public/pw_preprocessor/compiler.h): `pw_preprocessor/public/pw_preprocessor/compiler.h`
- [Span](https://github.com/pigweed-project/pigweed/blob/main/pw_span/public/pw_span/span.h): `pw_span/public/pw_span/span.h`
- [Status](https://github.com/pigweed-project/pigweed/blob/main/pw_status/public/pw_status/status.h): `pw_status/public/pw_status/status.h`
- [Result](https://github.com/pigweed-project/pigweed/blob/main/pw_result/public/pw_result/result.h): `pw_result/public/pw_result/result.h`
- [Containers](https://github.com/pigweed-project/pigweed/blob/main/pw_containers/public/pw_containers/vector.h): `pw_containers/public/pw_containers/vector.h`

### Runtime and concurrency

- [Async tasks](https://github.com/pigweed-project/pigweed/blob/main/pw_async2/public/pw_async2/task.h): `pw_async2/public/pw_async2/task.h`
- [Futures](https://github.com/pigweed-project/pigweed/blob/main/pw_async2/public/pw_async2/future.h): `pw_async2/public/pw_async2/future.h`
- [Synchronization](https://github.com/pigweed-project/pigweed/blob/main/pw_sync/public/pw_sync/lock_annotations.h): `pw_sync/public/pw_sync/lock_annotations.h`

### Memory and storage

- [Allocators](https://github.com/pigweed-project/pigweed/blob/main/pw_allocator/public/pw_allocator/allocator.h): `pw_allocator/public/pw_allocator/allocator.h`
- [Deallocation](https://github.com/pigweed-project/pigweed/blob/main/pw_allocator/public/pw_allocator/deallocator.h): `pw_allocator/public/pw_allocator/deallocator.h`
- [Blob store](https://github.com/pigweed-project/pigweed/blob/main/pw_blob_store/blob_store.cc): `pw_blob_store/blob_store.cc`

### Communications

- [RPC server](https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/public/pw_rpc/server.h): `pw_rpc/public/pw_rpc/server.h`
- [RPC query service](https://github.com/pigweed-project/pigweed/blob/main/pw_rpc/pwpb/query_service.cc): `pw_rpc/pwpb/query_service.cc`
- [Data transfer](https://github.com/pigweed-project/pigweed/blob/main/pw_transfer/client_context.cc): `pw_transfer/client_context.cc`
- [Bluetooth APIs](https://github.com/pigweed-project/pigweed/blob/main/pw_bluetooth/public/pw_bluetooth/emboss_util.h): `pw_bluetooth/public/pw_bluetooth/emboss_util.h`
- [Bluetooth proxy](https://github.com/pigweed-project/pigweed/blob/main/pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc): `pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc`

### Diagnostics

- [Assertions](https://github.com/pigweed-project/pigweed/blob/main/pw_assert/public/pw_assert/assert.h): `pw_assert/public/pw_assert/assert.h`
- [Checks](https://github.com/pigweed-project/pigweed/blob/main/pw_assert/public/pw_assert/check.h): `pw_assert/public/pw_assert/check.h`
- [Logging](https://github.com/pigweed-project/pigweed/blob/main/pw_log/public/pw_log/log.h): `pw_log/public/pw_log/log.h`

### Other components

- **Firmware engineer**

## Connections

- Firmware engineer → Allocators: selects modules (evidence: `README.md`)
- Firmware engineer → Async tasks: selects modules (evidence: `README.md`)
- Firmware engineer → RPC server: selects modules (evidence: `README.md`)
- Firmware engineer → Bluetooth APIs: selects modules (evidence: `README.md`)
- RPC server → Containers: uses lists (evidence: `pw_rpc/public/pw_rpc/server.h`)
- RPC server → Span: uses spans (evidence: `pw_rpc/public/pw_rpc/server.h`)
- RPC server → Status: uses status (evidence: `pw_rpc/public/pw_rpc/server.h`)
- RPC query service → RPC server: registers and queries (evidence: `pw_rpc/pwpb/query_service.cc`)
- RPC query service → Status: returns status (evidence: `pw_rpc/pwpb/query_service.cc`)
- Bluetooth proxy → Bluetooth APIs: uses packet utilities (evidence: `pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc`)
- Bluetooth proxy → Assertions: checks conditions (evidence: `pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc`)
- Bluetooth proxy → Logging: logs events (evidence: `pw_bluetooth_proxy/credit_based_flow_control_rx_engine.cc`)
- Futures → Status: uses status
- Data transfer → RPC server: uses RPC
