# lightning/bolts architecture

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

- Interactive diagram: https://gitdiagram.com/lightning/bolts
- Repository: https://github.com/lightning/bolts

## Overview

##### Main Components
a. Specification Documents: These are the markdown files (00-introduction.md, 01-messaging.md, 02-peer-protocol.md, …, 11-payment-encoding.md, 12-offer-encoding.md) which describe the protocols. They form the core “knowledge base” for the Lightning Network specs.
b. BOLT-Specific Directories: The directories “bolt04”, “bolt07”, and “bolt12” contain JSON test files and examples. They represent test cases and example formats for each of the critical protocol areas.
c. Proposals: The “proposals” directory (e.g., proposals/route-blinding.md) shows community or experimental additions for new protocol features.
d. Tools: The “tools” directory includes scripts (e.g., bolt3-bitcoind-test.sh, extract-formats.py, spellcheck.sh) that help validate and maintain consistency in the specs.
e. CI/CD and Contribution Artifacts: Files like .travis.yml, CONTRIBUTING.md, CoC.md, and the .gitattributes indicate how the project is maintained and integrated into a CI/CD pipeline.

##### Relationships and Data Flow
- The core protocol specification documents are the reference material.
- The BOLT directories provide concrete sample data/examples and tests that are linked to the protocols.
- The proposal files indicate potential changes or additions to these protocols.
- The tooling scripts interact with both the specification files and the test files for automated checks (e.g., to extract formats for validation or run tests against actual implementations).
- The CI/CD configuration (e.g., Travis CI) ties all these components together by automatically running tests and spell checks on the latest changes.

##### Architectural Patterns
- The project exhibits a “documentation-as-code” approach where the protocol specifications are maintained as versioned markdown files and test cases.
- There is a clear separation between the specification content (the “what” of the protocols) and the validation tools (the “how” they are verified and maintained).
- Although there is no runtime application, the pattern of separation is similar to a “layered architecture” with clear validation (test examples and tools) and content layers.

- A block for the core documentation (all the numbered markdown files).
- Separate blocks for the test directories: bolt04, bolt07, bolt12.
- A block for Proposals.
- A block for Tools.
- An integration block for CI/CD (Travis CI) and additional contribution guidelines (CONTRIBUTING.md, CoC.md).
- Specifications → BOLT Test Files (Validation)
- Tools → both Specifications and Test Files (Automated Operations)
- Proposals → Specifications (Feedback Loop)
- CI/CD → Tools/Tests/Specs (Automation Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Protocol Specifications"]:::spec
    B["BOLT04 Test Cases"]:::bolt
    C["BOLT07 Test Cases"]:::bolt
    D["BOLT12 Test Cases"]:::bolt
    E["Community Proposals"]:::proposal
    F["Validation Tools"]:::tool
    G["CI/CD Infrastructure"]:::cicd

    A -->|"validates"| B
    A -->|"validates"| C
    A -->|"validates"| D

    F -->|"validates"| A
    F -->|"validates"| B
    F -->|"validates"| C
    F -->|"validates"| D

    E -->|"feedback"| A

    G -->|"triggers"| F
    G -->|"runs"| A
    G -->|"executes"| B
    G -->|"executes"| C
    G -->|"executes"| D
    G -->|"executes"| E

    click A "https://github.com/lightning/bolts/blob/master/00-introduction.md"
    click B "https://github.com/lightning/bolts/tree/master/bolt04"
    click C "https://github.com/lightning/bolts/tree/master/bolt07"
    click D "https://github.com/lightning/bolts/tree/master/bolt12"
    click E "https://github.com/lightning/bolts/tree/master/proposals"
    click F "https://github.com/lightning/bolts/tree/master/tools"
    click G "https://github.com/lightning/bolts/blob/master/.travis.yml"

    classDef spec fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef bolt fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef proposal fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef tool fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef cicd fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
