# stacks-network/stacks-core architecture

> Architecture diagram of the GitHub repository stacks-network/stacks-core, 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/stacks-network/stacks-core
- Repository: https://github.com/stacks-network/stacks-core

## Overview

##### Main Components
- Stacks Node & Consensus: At the heart, there is a “stacks-node” component (located in testnet/stacks-node and other parts of the repository) implementing the core node logic, consensus, block production, leader election (tied to Bitcoin’s PoX), and block propagation.
- Clarity Virtual Machine & Smart Contract Engine: The “clarity” directory contains the implementation of the Clarity language interpreter/Vm (with AST parsers, type checkers, cost functions, and contracts analysis). This is critical for executing smart contracts.
- Networking and P2P Layers: There are extensive “net” and “stacks-common” components that manage P2P communications, Bitcoin interactions (anchoring to Bitcoin), and network protocols.
- Wallet/Signing & Database Support: Components such as “libsigner” and “stacks-signer” handle signing operations, session management, and client interactions, while “libstackerdb” and related database layers are used for chain state storage and query.
- Utility, Testing & Infrastructure: Several directories (like “contrib”, “net-test”, “migration-verification”, “sample”, “docs”, and various GitHub Actions workflows) support automated tests, integration tests, testnet deployments, fuzzing, containerized builds (dockerfiles), and other devops tooling.
- External Interactions: The project uses external dependencies such as Bitcoin’s blockchain (for security anchoring via PoX) and external scripts (for genesis, deployments, and miner integrations).

##### Relationships and Interactions
- Consensus and PoX: Illustrate the PoX process whereby the node periodically interacts with the Bitcoin base layer, so include a “Bitcoin” external element that feeds into the leader election and block validation.
- Testing Infrastructure: Connect components such as “net-test”, “migration-verification”, and “boot-contracts-tests” that simulate or stress-test various parts of the system.
- Developer Tools: Indicate components for fuzz testing (under clarity/fuzz) and containerization (Dockerfiles under .github/actions) that help automate builds, tests, and deployment.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separate the system logically into layers (e.g., low-level database and chainstate, mid-level consensus and networking, and high-level smart contract execution).
- Test-Driven/Integration Design: Emphasize the dedicated test suites and integration test environments (testnet, boot-contract tests, etc.) that simulate production behavior.
- Extensibility and Plugin Points: Indicate areas (like the Clarity language processing and the API endpoints) that serve as natural extension or integration points for decentralized applications and improvements (SIPs).

##### Relevant Technologies and Frameworks
- Rust: The entire project is implemented in Rust, so annotate that each component is built on a Rust codebase.
- Docker & CI/CD Pipelines: Since there are numerous Dockerfiles and GitHub workflows, include a block for CI/CD (build, lint, test, release) that ties into each component.
- External Services: Although not “services” in a microservices sense, include how the system communicates with the Bitcoin network and potentially external monitoring endpoints (Prometheus in monitoring modules).

- Clear labeled components for each module: “Stacks Node (Consensus & Block Production)”, “Clarity VM (Smart Contract Processing)”, “Networking & P2P Layer”, “Signing & Client Tools”, “Database/Chain State”, and “CI/CD & Testing Infrastructure.”
– From “Stacks Node” to “Clarity VM” (for smart contract execution).
– From “Stacks Node” to “Bitcoin” (representing PoX and leader election).
– Communication paths among “Networking”, “API endpoints”, and “Database”.
- Notations for build tools and development workflows (Docker containers, GitHub Actions, etc.) linking to the components they interact with.

##### Be Very Detailed and Decompose the System
- For the “Stacks Node”, further break it into submodules such as consensus, networking, event dispatchers, and monitoring channels.
- Where applicable, indicate test and benchmark environments which are substantial given the number of test directories and configurations included.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Component
    Bitcoin["Bitcoin Network"]:::external

    %% Blockchain Core Subgraph
    subgraph "Blockchain Core"
        SN["Stacks Node (Consensus & Block Production)"]:::node
        CVM["Clarity VM (Smart Contract Processing)"]:::vm
    end

    %% Network Layer Subgraph
    subgraph "Network Layer"
        NET["Networking & P2P Layer"]:::network
    end

    %% Services Subgraph
    subgraph "Supporting Services"
        SIGN1["libsigner"]:::sign
        SIGN2["stacks-signer"]:::sign
        DB["Database/Chain State"]:::db
    end

    %% DevOps & Testing Subgraph
    subgraph "DevOps & Testing"
        UTILS["Testing & Infrastructure (contrib, net-test, migration-verification)"]:::utils
        CICD["CI/CD & GitHub Actions"]:::infra
    end

    %% Relationships
    Bitcoin -->|"feeds_PoX"| SN
    SN -->|"executes_contracts"| CVM
    SN -->|"communicates"| NET
    NET -->|"responds_to"| SN
    SN -->|"triggers_signing"| SIGN1
    SN -->|"triggers_signing"| SIGN2
    SN -->|"updates_state"| DB
    NET -->|"queries_state"| DB
    UTILS -->|"integration_tests"| SN
    CICD -->|"build_deploy"| SN
    CICD -->|"build_deploy"| CVM
    CICD -->|"build_deploy"| NET
    CICD -->|"build_deploy"| SIGN1
    CICD -->|"build_deploy"| SIGN2
    CICD -->|"build_deploy"| DB

    %% Click Events
    click SN "https://github.com/stacks-network/stacks-core/tree/master/testnet/stacks-node"
    click CVM "https://github.com/stacks-network/stacks-core/tree/master/clarity"
    click NET "https://github.com/stacks-network/stacks-core/tree/master/stacks-common"
    click SIGN1 "https://github.com/stacks-network/stacks-core/tree/master/libsigner"
    click SIGN2 "https://github.com/stacks-network/stacks-core/tree/master/stacks-signer"
    click DB "https://github.com/stacks-network/stacks-core/tree/master/libstackerdb"
    click UTILS "https://github.com/stacks-network/stacks-core/tree/master/contrib"
    click CICD "https://github.com/stacks-network/stacks-core/tree/master/.github/actions"

    %% Styles
    classDef external fill:#ffe6f0,stroke:#cc0044,stroke-width:2px;
    classDef node fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef vm fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef sign fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef db fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef utils fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef infra fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
