# ton-org/blueprint architecture

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

- Interactive diagram: https://gitdiagram.com/ton-org/blueprint
- Repository: https://github.com/ton-org/blueprint

## Overview

##### Project Type & Purpose
- This project is a developer tool designed to streamline the process of creating, compiling, testing, and deploying TON blockchain smart contracts written in FunC, Tact, and Tolk.
- Its core functionality includes project scaffolding, compilation of contracts, running tests (using Sandbox), deploying via various wallet/deeplink integrations (e.g., TON Connect), and supporting a plugins ecosystem.
- The README emphasizes its usage as a CLI tool (invoked via commands like “npx blueprint build”) that manages workflows for contract development.

##### File Structure
- Top-Level Folders:
– The “src” directory contains the core codebase including CLI commands (src/cli), compiler configuration and processing (src/compile), configuration handling (src/config), and network integration (src/network).
– The “example” folder mirrors a typical project structure for a user-created project, with directories for contracts, compilables, tests, wrappers, and scripts.
– The “src/templates” directory holds a variety of contract templates (for different languages: func, tact, tolk) which defines how new projects or contracts are scaffolded.
– Other configuration and support files (.github, package.json, tsconfig.json, etc.) are present for CI/CD and overall project configuration.
- Key Architectural Patterns:
– Separation of concerns: There is a clear modular division between CLI logic, compilation, network operations, configuration management, and templating.
– Plugin architecture: As indicated in the README and supported by its config submodules, a dynamic plugin system is in place to allow extension without modifying core code.
– Multi-language support: The project supports different smart contract languages (each with its own template and compilation path), which is clearly represented by the well-organized “src/templates” structure.

##### Main Components
A. CLI Interface & Command Runner:
- Location: src/cli (files like cli.ts, Runner.ts, various command modules such as build, test, run, set, etc.)
- Role: Serves as the entry point for user commands; parses inputs and orchestrates the invocation of the appropriate subsystems.
B. Compiler Subsystem:
- Location: src/compile and related virtual file system support (OverwritableVirtualFileSystem.ts).
- Role: Handles compilation of smart contracts using external compilers for FunC, Tact, and Tolk. Outputs artifacts to the build directory.
C. Configuration & Plugin Manager:
- Location: src/config (Config.ts, Plugin.ts, etc.)
- Role: Reads and applies the user’s configurations and loaded plugins (which may alter or extend features of the main application).
D. Network Provider & Deployment:
- Location: src/network including directories “send” (with providers like TonConnectProvider.ts, MnemonicProvider.ts) and “storage” (FSStorage.ts).
- Role: Manages blockchain connectivity, sending transactions, and deployment/verification processes.
E. Templating & Project Scaffolding:
- Location: src/templates, where separate directories for “func”, “tact”, “tolk”, and variants (counter, empty, legacy, etc.) are maintained.
- Role: Provides blueprints for project or contract creation, encapsulating best practices in separate, re-usable templates.
F. User Interface Layer:
- Location: src/ui (InquirerUIProvider.ts, UIProvider.ts).
- Role: Provides interactive prompts and UI support for the CLI, enhancing the developer experience.
G. Utility Modules:
- Location: src/utils.
- Role: Provide helper functions for object manipulation, selection handling, timing, and TON-specific utilities.

##### Relationships & Data Flow
- The CLI acts as the central orchestrator, accepting user commands and input, then calling into the Configuration Manager to load settings and plugins.
- In project scaffolding or contract creation commands, the Template Engine fetches the appropriate blueprints from the “src/templates” directory.
- Data flows from the CLI to the relevant subsystems (compiler, network, etc.), with feedback and logs returned, possibly also using the UI module for interactive commands.

##### Architectural Patterns & Technologies
- Command Pattern: Different CLI commands are modularized (build, run, test, etc.), each with a dedicated module.
- Plugin Architecture: The configuration system is prepared for plugins (as also shown in the README examples), allowing external community additions.
- Multi-language Compilation: By supporting FunC, Tact, and Tolk through distinct template and compiler modules, the architecture decouples language-specific concerns.
- External Dependencies: Usage of external libraries for compilation (func-js, tolk-js, tact), testing (Sandbox), and deployment (TON Connect library).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs for vertical stacking
    subgraph "Presentation Layer"
        UI["User Interface Layer"]:::presentation
        CLI["CLI Interface & Command Runner"]:::presentation
    end

    subgraph "Core Business Logic"
        CFG["Configuration & Plugin Manager"]:::business
        COMP["Compiler Subsystem"]:::business
        NET["Network Provider & Deployment"]:::business
        TEMP["Templating & Project Scaffolding"]:::business
    end

    subgraph "Utility Layer"
        UTIL["Utility Modules"]:::utility
    end

    %% Connections
    UI -->|"user-command"| CLI
    CLI -->|"load-config"| CFG
    CLI -->|"invoke-compiler"| COMP
    CLI -->|"init-deployment"| NET
    CLI -->|"fetch-blueprint"| TEMP
    CLI -->|"use-helpers"| UTIL

    CFG -->|"extend-compiler"| COMP
    CFG -->|"network-settings"| NET

    COMP -->|"utilize-helpers"| UTIL

    %% Click Events
    click CLI "https://github.com/ton-org/blueprint/tree/main/src/cli"
    click COMP "https://github.com/ton-org/blueprint/tree/main/src/compile"
    click CFG "https://github.com/ton-org/blueprint/tree/main/src/config"
    click NET "https://github.com/ton-org/blueprint/tree/main/src/network"
    click TEMP "https://github.com/ton-org/blueprint/tree/main/src/templates"
    click UI "https://github.com/ton-org/blueprint/tree/main/src/ui"
    click UTIL "https://github.com/ton-org/blueprint/tree/main/src/utils"

    %% Styles
    classDef presentation fill:#ffebcd,stroke:#d2691e,stroke-width:2px;
    classDef business fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef utility fill:#98fb98,stroke:#2e8b57,stroke-width:2px;
```
