# fabriclabs/fabric architecture

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

- Interactive diagram: https://gitdiagram.com/fabriclabs/fabric
- Repository: https://github.com/fabriclabs/fabric

## Overview

##### Project Type and Purpose
- Project Type: Open-source reference client library & CLI for building peer-to-peer apps on Bitcoin.
- Purpose: Provide a JavaScript API (actor-model, event emitter) plus CLI tools to run Fabric nodes, interact with blockchains, and extend via plugins/services.

##### File Structure
- Top-Level Folders:
- `/types`: JS classes (Peer, Chain, Message, Contract, etc.) defining core abstractions.
- `/services`: Adapters for blockchain & network services (bitcoin, lightning, redis, zmq, local, etc.).
- `/schemata`: JSON schemas for message validation.
- `/stores`: Persistence layers (LevelDB, in-memory).
- `/scripts`: Command‐line scripts to spin up nodes, playnets, wallets, benchmarks.
- `/examples` & `/assets`: Front-end examples and static assets for demo web UIs.
- `/docs`: Generated API docs and guides.
- `/functions`: Utility functions (error handling, JSON/HTML formatting).
- `/settings`: Environment configurations (playnet, local, test).
- `/tests`: Unit/integration tests covering all modules.
- Configuration Files:
- `package.json`, `nix` files, `.envrc`, `.gitignore`.
- Build & CI workflows under `.github/workflows`.

##### Core Components & Boundaries
A. Fabric Core Node (Peer)
- Implements actor model, event emitter
- Loads modules from `/types`
- Manages protocol state (chain, mempool, contracts, sessions)
- Publishes and subscribes to messages
B. Services Layer
- Bitcoin Service (bitcoind RPC)
- Lightning Service (Lightning Daemon)
- Redis Service (pub/sub, caching)
- ZMQ Service (message bus)
- Local Service (in-process stub)
- Turntable, TXT, Exchange, etc.
Each service knows how to connect to its external system, expose data/events to the Core Node.
C. Persistence Layer (Stores)
- LevelDB or in-memory stores for blocks, transactions, state snapshots.
D. Schemata & Validation
- JSON schema definitions used by Core Node to validate incoming/outgoing messages.
E. CLI & Developer Interfaces
- `fabric` CLI (invokes scripts under `/scripts`)
- `npm run dev` HTTP dev interface
- `npm run docs` and `npm run examples` for local servers
F. Plugins & Extensions
- HTTP plugin, Hub plugin, Doorman, Zapier, etc.
- Each plugin subscribes to core events and provides an external interface.
G. External Systems
- Bitcoin full node (`bitcoind`)
- Lightning node
- Other Fabric peers (p2p network over TCP/ZeroMQ)
- Browser front-end (for examples)

##### Relationships and Data Flows
- CLI/Dev Interface ← listens to Core Node events and issues commands.

##### Architectural Patterns & Principles
- Actor Model / Event-Driven: everything communicates via messages/events.
- Modular & Plugin-Based: core logic is separated from service adapters and plugins.
- Layered: API layer (types), service adapters, persistence, transport.

##### Technologies & Frameworks
- Node.js (v16+), native modules: `secp256k1`, `level`, `zeromq`.
- JSON Schema for message validation.
- ZeroMQ / Redis for pub/sub.
- HTTP (Express or similar) for dev server.
- LevelDB for local storage.
- Nix/devshell for reproducible environments.

##### Essential Checklist
- [ ] Services adapters grouped together.
- [ ] Persistence layer (stores).
- [ ] Schemata validation component.
- [ ] Plugin boundary highlighting HTTP/Hub/Doorman.
- [ ] External dependencies (bitcoind, lightning, other Fabric peers).
- [ ] Developer interfaces (CLI, HTTP, Examples).

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Interfaces Layer
  subgraph "Interfaces" 
    CLI["CLI Entrypoint\n(scripts/cli.js)"]:::interface
    REPL["Node Startup & REPL\n(scripts/node.js)"]:::interface
    HTTP["Dev HTTP Interface\n(scripts/app.js)"]:::interface
  end

  %% Core Node Layer
  subgraph "Core Node" 
    peer["Fabric Core Node\n(types/peer.js, types/node.js, types/fabric.js)"]:::core
    actor["Actor Model & Event Emitter\n(types/actor.js)"]:::core
    subgraph "Chain State Management"
      chain["Chain\n(types/chain.js)"]:::core
      mempool["Mempool\n(types/mempool.js)"]:::core
      session["Session\n(types/session.js)"]:::core
      contract["Contract\n(types/contract.js)"]:::core
    end
  end

  %% Services Layer
  subgraph "Services Layer"
    bitcoin["Bitcoin Service\n(services/bitcoin.js)"]:::service
    lightning["Lightning Service\n(services/lightning.js)"]:::service
    redisService["Redis Service\n(services/redis.js)"]:::service
    zmqService["ZeroMQ Service\n(services/zmq.js)"]:::service
    localService["Local Service\n(services/local.js)"]:::service
    turntable["Turntable Plugin\n(services/turntable.js)"]:::service
    txt["TXT Plugin\n(services/txt.js)"]:::service
    exchange["Exchange Plugin\n(services/exchange.js)"]:::service
  end

  %% Persistence Layer
  stores["Persistence Layer\n(stores/)"]:::storage

  %% Schema Validation
  schemata["JSON Schema Validation\n(schemata/index.js & .json)"]:::schema

  %% External Systems
  subgraph "External Systems"
    bitcoind["Bitcoin Full Node\n(bitcoind)"]:::external
    lnNode["Lightning Node"]:::external
    peerNet["Peer Network\n(P2P over TCP/ZMQ)"]:::external
    browser["Browser Front-End"]:::external
  end

  %% Connections
  CLI -->|"starts"| peer
  REPL -->|"starts"| peer
  HTTP -->|"HTTP API"| peer

  peer -->|"uses actor model"| actor
  peer -->|"manages state"| chain
  peer -->|"manages state"| mempool
  peer -->|"manages state"| session
  peer -->|"manages state"| contract

  peer -->|"sync RPC"| bitcoin
  peer -->|"sync RPC"| lightning

  peer -.->|"pub/sub events"| redisService
  peer -.->|"pub/sub events"| zmqService

  bitcoin -->|"RPC calls"| bitcoind
  lightning -->|"RPC calls"| lnNode
  redisService -->|"connects"| redisService
  zmqService -->|"connects"| peerNet
  localService --- peer

  turntable -.->|"plugin hook"| peer
  txt -.->|"plugin hook"| peer
  exchange -.->|"plugin hook"| peer

  peer -->|"read/write"| stores
  peer -->|"validate messages"| schemata

  peer -->|"P2P messages"| peerNet
  HTTP -->|"serves UI"| browser

  %% Click Events
  click peer "https://github.com/fabriclabs/fabric/blob/master/types/peer.js"
  click actor "https://github.com/fabriclabs/fabric/blob/master/types/actor.js"
  click chain "https://github.com/fabriclabs/fabric/blob/master/types/chain.js"
  click mempool "https://github.com/fabriclabs/fabric/blob/master/types/mempool.js"
  click session "https://github.com/fabriclabs/fabric/blob/master/types/session.js"
  click contract "https://github.com/fabriclabs/fabric/blob/master/types/contract.js"
  click bitcoin "https://github.com/fabriclabs/fabric/blob/master/services/bitcoin.js"
  click lightning "https://github.com/fabriclabs/fabric/blob/master/services/lightning.js"
  click redisService "https://github.com/fabriclabs/fabric/blob/master/services/redis.js"
  click zmqService "https://github.com/fabriclabs/fabric/blob/master/services/zmq.js"
  click localService "https://github.com/fabriclabs/fabric/blob/master/services/local.js"
  click turntable "https://github.com/fabriclabs/fabric/blob/master/services/turntable.js"
  click txt "https://github.com/fabriclabs/fabric/blob/master/services/txt.js"
  click exchange "https://github.com/fabriclabs/fabric/blob/master/services/exchange.js"
  click stores "https://github.com/fabriclabs/fabric/tree/master/stores/"
  click schemata "https://github.com/fabriclabs/fabric/blob/master/schemata/index.js"
  click CLI "https://github.com/fabriclabs/fabric/blob/master/scripts/cli.js"
  click REPL "https://github.com/fabriclabs/fabric/blob/master/scripts/node.js"
  click HTTP "https://github.com/fabriclabs/fabric/blob/master/scripts/app.js"

  %% Styles
  classDef core fill:#e0f7fa,stroke:#006064,color:#004d40
  classDef service fill:#fff3e0,stroke:#e65100,color:#bf360c
  classDef interface fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
  classDef storage fill:#fffde7,stroke:#f9a825,color:#f57f17
  classDef schema fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
  classDef external fill:#eceff1,stroke:#37474f,color:#263238
```
