# brighter47/canopy architecture

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

- Interactive diagram: https://gitdiagram.com/brighter47/canopy
- Repository: https://github.com/brighter47/canopy

## Overview

#### Purpose and Runtime Entry Points
Canopy is the Go reference implementation of the Canopy Network Protocol: a recursive blockchain framework plus seed chain. The node binary starts at `cmd/main/main.go`; command-line administration and queries are in `cmd/cli/cli.go`, `cmd/cli/admin.go`, and `cmd/cli/query.go`. The runtime is primarily Go 1.21, with a TypeScript browser wallet and explorer served independently from the node.

#### Node Orchestration
The controller is the central coordination boundary between networking, consensus, transaction handling, state transitions, and persistence. It owns block/consensus coordination and routes node-level work rather than embedding domain rules itself.
- `controller/controller.go`
- `controller/consensus.go`
- `controller/block.go`

Primary flow: P2P-delivered transactions and consensus messages enter controller-managed paths; accepted blocks are executed through the FSM and committed to storage.

#### Deterministic State Machine
The FSM defines consensus-critical validation and state mutation. It handles accounts, validators/committees, governance, DEX and swaps, Ethereum-oriented functionality, events, genesis, and transaction/message interpretation. State logic must remain deterministic because every validator executes it for the same block.
- `fsm/state.go`
- `fsm/transaction.go`
- `fsm/automatic.go`
- `fsm/gov.go`
- `fsm/dex.go`

#### BFT Consensus Pipeline
The BFT package implements proposer selection/election, proposals, votes, evidence, and consensus messages. It produces agreement on a block before the controller applies its state transition; evidence represents the fault-handling boundary for Byzantine behavior.
- `bft/bft.go`
- `bft/election.go`
- `bft/prop.go`
- `bft/vote.go`
- `bft/evidence.go`

#### P2P Transport and Cryptographic Boundary
Nodes discover and maintain peers, exchange protocol messages, and encrypt connections through the P2P subsystem. Cryptographic identity, signatures, key storage, hashing, BLS, secp256k1/Ed25519, and Ethereum secp256k1 support sit in shared library code. P2P supplies the distributed transport; consensus and controller own message semantics.
- `p2p/p2p.go`
- `p2p/conn.go`
- `p2p/encrypt.go`
- `lib/crypto/key.go`
- `lib/crypto/keystore.go`

#### Persistence, Data Models, and Wire Contracts
Storage maintains versioned chain state, sparse Merkle-tree verification, transactional updates, and historical indexing. Shared `lib` types cover blocks, transactions, certificates, configuration, peers, mempool, and plugin contracts. Protobuf definitions are the canonical cross-package/wire schema source, with generated Go bindings checked in.
- `store/versioned_store.go`
- `store/smt.go`
- `store/indexer.go`
- `lib/.proto/tx.proto`
- `lib/.proto/consensus.proto`

#### External Interfaces: RPC, UIs, and Plugins
The RPC server exposes query, administration, Ethereum-facing, and client routes over server/socket layers. Two TypeScript/Vite applications consume node-facing APIs: an explorer and a wallet. The wallet contains a manifest-driven declarative action engine that renders forms and submits action workflows. Plugin SDKs let independently implemented chain/plugin logic communicate through protobuf/RPC contracts in Go, C#, Kotlin, Python, or TypeScript.
- `cmd/rpc/server.go`
- `cmd/rpc/routes.go`
- `cmd/rpc/eth.go`
- `cmd/rpc/web/wallet/src/actions/ActionRunner.tsx`
- `cmd/rpc/web/explorer/src/lib/api.ts`
- `plugin/go/contract/plugin.go`

#### Deployment and Automation
Docker Compose provides a multi-node local network with per-node genesis, validator keys, keystores, and persisted state fixtures. Auto-update is a separate Go service with language-specific container images for plugin release/update coordination.
- `.docker/compose.yaml`
- `.docker/volumes/node_1/genesis.json`
- `.docker/volumes/node_1/validator_key.json`
- `cmd/auto-update/main.go`

Main entry points: [`controller/controller.go`](https://github.com/brighter47/canopy/blob/main/controller/controller.go) (Controller), [`cmd/rpc/server.go`](https://github.com/brighter47/canopy/blob/main/cmd/rpc/server.go) (RPC server), [`bft/bft.go`](https://github.com/brighter47/canopy/blob/main/bft/bft.go) (BFT consensus), [`fsm/state.go`](https://github.com/brighter47/canopy/blob/main/fsm/state.go) (Deterministic FSM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Node Runtime"]
  node_node_binary["Node binary<br/>Go entry point<br/>[main.go]"]
  node_cli["CLI<br/>[cli.go]"]
  node_controller["Controller<br/>node coordinator<br/>[controller.go]"]
  node_block_coordination["Block coordination<br/>controller layer<br/>[block.go]"]
end

subgraph group_core["Protocol Core"]
  node_bft{{"BFT consensus<br/>consensus engine<br/>[bft.go]"}}
  node_p2p["P2P transport<br/>encrypted peer network<br/>[p2p.go]"]
  node_crypto["Cryptography<br/>shared crypto library<br/>[key.go]"]
  node_fsm{{"Deterministic FSM<br/>state transition engine<br/>[state.go]"}}
  node_governance_dex["Governance and DEX<br/>FSM domains<br/>[gov.go]"]
  node_store[("Versioned store<br/>chain persistence<br/>[versioned_store.go]")]
  node_smt_index["SMT and indexer<br/>storage layer<br/>[smt.go]"]
  node_wire_contracts["Protobuf contracts<br/>wire schema<br/>[tx.proto]"]
  node_shared_types["Shared protocol types<br/>Go library"]
end

subgraph group_interfaces["External Interfaces"]
  node_rpc["RPC server<br/>node API<br/>[server.go]"]
  node_wallet["Browser wallet<br/>TypeScript/Vite app<br/>[ActionRunner.tsx]"]
  node_explorer["Block explorer<br/>TypeScript/Vite app<br/>[api.ts]"]
  node_plugin_sdk["Plugin SDKs<br/>multi-language contracts<br/>[plugin.go]"]
end

subgraph group_operations["Deployment"]
  node_compose_network["Local multi-node network<br/>Docker Compose<br/>[compose.yaml]"]
  node_auto_update["Auto-update service<br/>Go service<br/>[main.go]"]
end

node_node_binary -->|"starts"| node_controller
node_cli -->|"admin and query"| node_rpc
node_controller -->|"coordinates"| node_block_coordination
node_p2p -->|"transactions and messages"| node_controller
node_controller -->|"drives agreement"| node_bft
node_bft -->|"agreed block"| node_block_coordination
node_block_coordination -->|"executes block"| node_fsm
node_fsm -->|"applies domain rules"| node_governance_dex
node_fsm -->|"commits state"| node_store
node_store -->|"verifies and indexes"| node_smt_index
node_p2p -->|"encrypted identities"| node_crypto
node_bft -->|"signatures"| node_crypto
node_bft -->|"consensus schema"| node_wire_contracts
node_fsm -->|"blocks and transactions"| node_shared_types
node_rpc -->|"node operations"| node_controller
node_rpc -->|"queries"| node_store
node_wallet -->|"API calls"| node_rpc
node_explorer -->|"API calls"| node_rpc
node_plugin_sdk -->|"protobuf/RPC contracts"| node_wire_contracts
node_auto_update -->|"plugin releases"| node_plugin_sdk
node_compose_network -->|"runs validator nodes"| node_node_binary

click node_node_binary "https://github.com/brighter47/canopy/blob/main/cmd/main/main.go"
click node_cli "https://github.com/brighter47/canopy/blob/main/cmd/cli/cli.go"
click node_controller "https://github.com/brighter47/canopy/blob/main/controller/controller.go"
click node_block_coordination "https://github.com/brighter47/canopy/blob/main/controller/block.go"
click node_bft "https://github.com/brighter47/canopy/blob/main/bft/bft.go"
click node_p2p "https://github.com/brighter47/canopy/blob/main/p2p/p2p.go"
click node_crypto "https://github.com/brighter47/canopy/blob/main/lib/crypto/key.go"
click node_fsm "https://github.com/brighter47/canopy/blob/main/fsm/state.go"
click node_governance_dex "https://github.com/brighter47/canopy/blob/main/fsm/gov.go"
click node_store "https://github.com/brighter47/canopy/blob/main/store/versioned_store.go"
click node_smt_index "https://github.com/brighter47/canopy/blob/main/store/smt.go"
click node_wire_contracts "https://github.com/brighter47/canopy/blob/main/lib/.proto/tx.proto"
click node_rpc "https://github.com/brighter47/canopy/blob/main/cmd/rpc/server.go"
click node_wallet "https://github.com/brighter47/canopy/blob/main/cmd/rpc/web/wallet/src/actions/ActionRunner.tsx"
click node_explorer "https://github.com/brighter47/canopy/blob/main/cmd/rpc/web/explorer/src/lib/api.ts"
click node_plugin_sdk "https://github.com/brighter47/canopy/blob/main/plugin/go/contract/plugin.go"
click node_compose_network "https://github.com/brighter47/canopy/blob/main/.docker/compose.yaml"
click node_auto_update "https://github.com/brighter47/canopy/blob/main/cmd/auto-update/main.go"

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_node_binary,node_cli,node_controller,node_block_coordination toneBlue
class node_bft,node_p2p,node_crypto,node_fsm,node_governance_dex,node_store,node_smt_index,node_wire_contracts,node_shared_types toneAmber
class node_rpc,node_wallet,node_explorer,node_plugin_sdk toneMint
class node_compose_network,node_auto_update toneRose
```

## Components

### Node Runtime

- [Node binary](https://github.com/brighter47/canopy/blob/main/cmd/main/main.go): Go entry point · `cmd/main/main.go`
- [CLI](https://github.com/brighter47/canopy/blob/main/cmd/cli/cli.go): administration client · Runs node administration and query commands. · `cmd/cli/cli.go`
- [Controller](https://github.com/brighter47/canopy/blob/main/controller/controller.go): node coordinator · Routes networking, consensus, block, and state work. · `controller/controller.go`
- [Block coordination](https://github.com/brighter47/canopy/blob/main/controller/block.go): controller layer · `controller/block.go`

### Protocol Core

- [BFT consensus](https://github.com/brighter47/canopy/blob/main/bft/bft.go): consensus engine · Elects proposers and processes proposals, votes, and evidence. · `bft/bft.go`
- [P2P transport](https://github.com/brighter47/canopy/blob/main/p2p/p2p.go): encrypted peer network · Discovers peers and exchanges protocol messages. · `p2p/p2p.go`
- [Cryptography](https://github.com/brighter47/canopy/blob/main/lib/crypto/key.go): shared crypto library · Provides identities, keys, signatures, hashes, and curves. · `lib/crypto/key.go`
- [Deterministic FSM](https://github.com/brighter47/canopy/blob/main/fsm/state.go): state transition engine · Consensus-critical transaction validation and state mutation. · `fsm/state.go`
- [Governance and DEX](https://github.com/brighter47/canopy/blob/main/fsm/gov.go): FSM domains · `fsm/gov.go`
- [Versioned store](https://github.com/brighter47/canopy/blob/main/store/versioned_store.go): chain persistence · Maintains versioned state and transactional commits. · `store/versioned_store.go`
- [SMT and indexer](https://github.com/brighter47/canopy/blob/main/store/smt.go): storage layer · Verifies sparse Merkle state and indexes history. · `store/smt.go`
- [Protobuf contracts](https://github.com/brighter47/canopy/blob/main/lib/.proto/tx.proto): wire schema · Canonical schemas for transactions and consensus messages. · `lib/.proto/tx.proto`
- **Shared protocol types**: Go library · Defines blocks, transactions, certificates, peers, and plugin contracts.

### External Interfaces

- [RPC server](https://github.com/brighter47/canopy/blob/main/cmd/rpc/server.go): node API · Exposes query, administration, client, and Ethereum-facing routes. · `cmd/rpc/server.go`
- [Browser wallet](https://github.com/brighter47/canopy/blob/main/cmd/rpc/web/wallet/src/actions/ActionRunner.tsx): TypeScript/Vite app · Renders manifest-driven actions and submits workflows. · `cmd/rpc/web/wallet/src/actions/ActionRunner.tsx`
- [Block explorer](https://github.com/brighter47/canopy/blob/main/cmd/rpc/web/explorer/src/lib/api.ts): TypeScript/Vite app · Consumes node-facing APIs. · `cmd/rpc/web/explorer/src/lib/api.ts`
- [Plugin SDKs](https://github.com/brighter47/canopy/blob/main/plugin/go/contract/plugin.go): multi-language contracts · Lets external chain and plugin implementations use protobuf/RPC contracts. · `plugin/go/contract/plugin.go`

### Deployment

- [Local multi-node network](https://github.com/brighter47/canopy/blob/main/.docker/compose.yaml): Docker Compose · Provides genesis, validator keys, keystores, and persistent fixtures. · `.docker/compose.yaml`
- [Auto-update service](https://github.com/brighter47/canopy/blob/main/cmd/auto-update/main.go): Go service · Coordinates language-specific plugin releases and updates. · `cmd/auto-update/main.go`

## Connections

- Node binary → Controller: starts
- CLI → RPC server: admin and query
- Controller → Block coordination: coordinates
- P2P transport → Controller: transactions and messages
- Controller → BFT consensus: drives agreement
- BFT consensus → Block coordination: agreed block
- Block coordination → Deterministic FSM: executes block
- Deterministic FSM → Governance and DEX: applies domain rules
- Deterministic FSM → Versioned store: commits state
- Versioned store → SMT and indexer: verifies and indexes
- P2P transport → Cryptography: encrypted identities
- BFT consensus → Cryptography: signatures
- BFT consensus → Protobuf contracts: consensus schema
- Deterministic FSM → Shared protocol types: blocks and transactions
- RPC server → Controller: node operations
- RPC server → Versioned store: queries
- Browser wallet → RPC server: API calls
- Block explorer → RPC server: API calls
- Plugin SDKs → Protobuf contracts: protobuf/RPC contracts
- Auto-update service → Plugin SDKs: plugin releases
- Local multi-node network → Node binary: runs validator nodes