# analog-labs/analog-gmp architecture

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

- Interactive diagram: https://gitdiagram.com/analog-labs/analog-gmp
- Repository: https://github.com/analog-labs/analog-gmp

## Overview

1. **Repository purpose**
   - This is a Solidity smart contract repository for Analog’s cross-chain messaging stack, centered on the **Analog General Message Passing (GMP)** protocol.
   - The repo is organized as a Foundry project, so the primary runtime is the **EVM** and the main build/test loop is **forge**.

2. **Top-level contract package**
   - The root `src/` directory is the main onchain contract code for the protocol.
   - The presence of `src/storage/` suggests the contracts separate **state layout / storage definitions** from higher-level protocol logic, which is important for upgradeable or tightly structured Solidity systems.

3. **GMP subproject**
   - The `gmp/` directory is a second Foundry package with its own `foundry.toml` and `README.md`.
   - Architecturally, this looks like a **nested module** or companion package for the General Message Passing components, likely used to isolate reusable protocol contracts, interfaces, or examples from the root package.

4. **Testing boundary**
   - The `test/` directory contains the Solidity tests for the contracts.
   - The CI workflow in `.github/workflows/test.yml` indicates the expected verification path is to compile and run Foundry tests on every change, so test coverage is a first-class part of the repo architecture.

5. **Storage as a distinct concern**
   - `src/storage/` is a clear boundary between **persistent contract state** and business logic.
   - That usually means the project is designed to keep storage schemas explicit and stable, which matters in protocol contracts where layout compatibility is critical.

6. **Build and developer tooling**
   - `foundry.toml` at the root and inside `gmp/` define separate build configurations, showing the repository supports more than one Solidity package boundary.
   - `remappings.txt` and `soldeer.lock` point to dependency management and import mapping as part of the project’s compilation model.

7. **Gas analysis workflow**
   - `plot_gas.py` and `forge snapshot` in the README show the repo includes **gas regression tracking**.
   - This matters architecturally because contract changes are likely evaluated not just for correctness but also for execution cost.

8. **Documentation pipeline**
   - The repo can generate docs with `forge doc -b`, and the README references `mdbook` for browsing them.
   - That implies the codebase is intended to be navigated as a protocol library, not just deployed contracts, with generated contract docs serving as a companion artifact.

9. **CI / quality gate**
   - `.github/workflows/test.yml` is the main automated gate visible in the tree.
   - The workflow likely mirrors local developer commands: build, test, and possibly formatting or snapshot checks.

10. **External integration context**
   - The only external system implied by the repo structure is the **Analog GMP protocol itself**, which is the cross-chain messaging layer these contracts target.
   - There are no signs of a frontend, API server, or offchain microservice architecture in this repository; the focus is on onchain protocol contracts and their verification tooling.

11. **How the pieces fit together**
   - Source contracts in `src/` define the protocol behavior and storage.
   - The `gmp/` package holds related GMP-specific artifacts.
   - Tests in `test/` validate behavior.
   - Foundry and CI handle compilation, regression checks, and packaging of documentation.

12. **Architecture summary for a diagram**
   - Draw this repo as a **Solidity protocol workspace** with two contract packages (`root` and `gmp`), a dedicated storage layer, a test/CI lane, and a gas-analysis/doc generation toolchain around the core contract code.

Main entry points: [`src`](https://github.com/analog-labs/analog-gmp/tree/main/src) (Protocol logic), [`gmp`](https://github.com/analog-labs/analog-gmp/tree/main/gmp) (GMP package), [`test`](https://github.com/analog-labs/analog-gmp/tree/main/test) (Tests), [`foundry.toml`](https://github.com/analog-labs/analog-gmp/blob/main/foundry.toml) (Foundry config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Protocol"]
  node_root_pkg["Root package<br/>foundry pkg"]
  node_protocol_logic["Protocol logic<br/>solidity contracts"]
  node_storage_layout[("Storage layout<br/>state schema")]
  node_gmp_pkg["GMP package<br/>nested pkg"]
  node_gmp_contracts["GMP contracts<br/>solidity module"]
end

subgraph group_verification["Verification"]
  node_tests["Tests"]
  node_ci["CI workflow<br/>github actions<br/>[test.yml]"]
  node_gas_profile["Gas profile<br/>benchmark script<br/>[plot_gas.py]"]
end

subgraph group_tooling["Tooling"]
  node_foundry_root["Foundry config<br/>build config<br/>[foundry.toml]"]
  node_foundry_gmp["GMP config<br/>build config<br/>[foundry.toml]"]
  node_remappings["Remappings<br/>import map<br/>[remappings.txt]"]
  node_deps["Dependencies<br/>lockfile<br/>[soldeer.lock]"]
  node_readme["Protocol docs<br/>markdown guide<br/>[README.md]"]
  node_gmp_readme["GMP docs<br/>markdown guide<br/>[README.md]"]
end

node_root_pkg -->|"contains"| node_protocol_logic
node_protocol_logic -->|"uses"| node_storage_layout
node_root_pkg -->|"includes"| node_gmp_pkg
node_gmp_pkg -->|"contains"| node_gmp_contracts
node_foundry_root -->|"builds"| node_root_pkg
node_foundry_gmp -->|"builds"| node_gmp_pkg
node_remappings -->|"supports"| node_root_pkg
node_deps -->|"pins"| node_root_pkg
node_tests -->|"verifies"| node_protocol_logic
node_tests -->|"verifies"| node_gmp_contracts
node_ci -->|"runs"| node_tests
node_ci -->|"uses"| node_foundry_root
node_gas_profile -->|"measures"| node_protocol_logic
node_readme -->|"documents"| node_foundry_root
node_readme -->|"documents"| node_gas_profile
node_gmp_readme -->|"documents"| node_gmp_pkg

click node_protocol_logic "https://github.com/analog-labs/analog-gmp/tree/main/src"
click node_storage_layout "https://github.com/analog-labs/analog-gmp/tree/main/src/storage"
click node_gmp_pkg "https://github.com/analog-labs/analog-gmp/tree/main/gmp"
click node_gmp_contracts "https://github.com/analog-labs/analog-gmp/tree/main/gmp/src"
click node_tests "https://github.com/analog-labs/analog-gmp/tree/main/test"
click node_ci "https://github.com/analog-labs/analog-gmp/blob/main/.github/workflows/test.yml"
click node_gas_profile "https://github.com/analog-labs/analog-gmp/blob/main/plot_gas.py"
click node_foundry_root "https://github.com/analog-labs/analog-gmp/blob/main/foundry.toml"
click node_foundry_gmp "https://github.com/analog-labs/analog-gmp/blob/main/gmp/foundry.toml"
click node_remappings "https://github.com/analog-labs/analog-gmp/blob/main/remappings.txt"
click node_deps "https://github.com/analog-labs/analog-gmp/blob/main/soldeer.lock"
click node_readme "https://github.com/analog-labs/analog-gmp/blob/main/README.md"
click node_gmp_readme "https://github.com/analog-labs/analog-gmp/blob/main/gmp/README.md"

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_root_pkg,node_protocol_logic,node_storage_layout,node_gmp_pkg,node_gmp_contracts toneBlue
class node_tests,node_ci,node_gas_profile toneAmber
class node_foundry_root,node_foundry_gmp,node_remappings,node_deps,node_readme,node_gmp_readme toneMint
```

## Components

### Protocol

Onchain Solidity contract packages and state layout

- **Root package**: foundry pkg · Main Solidity workspace for the GMP protocol
- [Protocol logic](https://github.com/analog-labs/analog-gmp/tree/main/src): solidity contracts · Primary contract behavior in the root src tree · `src`
- [Storage layout](https://github.com/analog-labs/analog-gmp/tree/main/src/storage): state schema · Explicit persistent storage definitions separated from logic · `src/storage`
- [GMP package](https://github.com/analog-labs/analog-gmp/tree/main/gmp): nested pkg · Secondary Foundry package for GMP-related contracts and artifacts · `gmp`
- [GMP contracts](https://github.com/analog-labs/analog-gmp/tree/main/gmp/src): solidity module · GMP-specific source code in the nested package · `gmp/src`

### Verification

Tests, CI, and gas regression checks

- [Tests](https://github.com/analog-labs/analog-gmp/tree/main/test): forge tests · Solidity test suite for contract behavior · `test`
- [CI workflow](https://github.com/analog-labs/analog-gmp/blob/main/.github/workflows/test.yml): github actions · Automated build and test gate · `.github/workflows/test.yml`
- [Gas profile](https://github.com/analog-labs/analog-gmp/blob/main/plot_gas.py): benchmark script · Gas snapshot and regression tracking via Python/Forge · `plot_gas.py`

### Tooling

Build, dependency, and documentation support

- [Foundry config](https://github.com/analog-labs/analog-gmp/blob/main/foundry.toml): build config · Root Foundry project configuration · `foundry.toml`
- [GMP config](https://github.com/analog-labs/analog-gmp/blob/main/gmp/foundry.toml): build config · Separate Foundry configuration for the nested GMP package · `gmp/foundry.toml`
- [Remappings](https://github.com/analog-labs/analog-gmp/blob/main/remappings.txt): import map · Solidity import resolution rules · `remappings.txt`
- [Dependencies](https://github.com/analog-labs/analog-gmp/blob/main/soldeer.lock): lockfile · Pinned package resolution state for Solidity dependencies · `soldeer.lock`
- [Protocol docs](https://github.com/analog-labs/analog-gmp/blob/main/README.md): markdown guide · Repository usage, build, and documentation entry point · `README.md`
- [GMP docs](https://github.com/analog-labs/analog-gmp/blob/main/gmp/README.md): markdown guide · Package-specific documentation for the nested GMP module · `gmp/README.md`

## Connections

- Root package → Protocol logic: contains · Root workspace houses the main contract implementation
- Protocol logic → Storage layout: uses · Protocol behavior reads and writes explicit storage definitions
- Root package → GMP package: includes · Repository contains a nested GMP-focused Foundry package
- GMP package → GMP contracts: contains · Nested package holds GMP-specific source code
- Foundry config → Root package: builds · Root Foundry config drives compilation of the main package
- GMP config → GMP package: builds · Nested Foundry config drives compilation of the GMP package
- Remappings → Root package: supports · Import mappings help resolve Solidity references
- Dependencies → Root package: pins · Dependency lockfile stabilizes builds for the root workspace
- Tests → Protocol logic: verifies · Forge tests exercise the main protocol contracts
- Tests → GMP contracts: verifies · Tests also cover GMP-specific behavior
- CI workflow → Tests: runs · CI executes the test suite on changes
- CI workflow → Foundry config: uses · Workflow relies on Foundry compilation and test commands
- Gas profile → Protocol logic: measures · Gas snapshots track protocol execution cost
- Protocol docs → Foundry config: documents · Repository guide explains the main Foundry workflow
- Protocol docs → Gas profile: documents · README references gas regression checks and snapshots
- GMP docs → GMP package: documents · Nested README explains the GMP subpackage