# yakuhito/slot-machine architecture

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

- Interactive diagram: https://gitdiagram.com/yakuhito/slot-machine
- Repository: https://github.com/yakuhito/slot-machine

## Overview

##### Project’s Purpose and Type
- This project is a Proof-of-Concept implementation for decentralized registration systems on the Chia blockchain. It implements two main functionalities:
- CATalog – a decentralized CAT registration system (for creating and registering new CATs with additional metadata and verification coins).
- XCHandles – a decentralized naming system that allows users to register names and associate an NFT with customizable information.
- The project combines Rust code (in the src directory) for CLI interactions and business logic with Chialisp smart contract puzzles (in the puzzles directory) that encode blockchain primitives.

##### File Structure to Extract Key Components
- Top-Level Files and Directories:
- .github/workflows: Contains CI/CD configurations (e.g., a Rust-specific workflow with rust.yml).
- Cargo.toml and Cargo.lock: Indicate that Rust is the primary backend language.
- README.md and LICENSE: Provide overall project documentation and licensing.
- build.sh: Likely a build or deployment script.
- Directory:
- Holds Chialisp libraries (.clib files) used by various puzzles for common functions such as condition codes, merkle utilities, and secure NFT operations.
- Puzzles Directory:
- Contains several subdirectories (actions, default_puzzles, nft, singleton, verification) where each holds smart contract code in Chialisp (.clsp) and their hex representations.
- The “actions” folder further subdivides into areas dedicated to catalog, dig-related actions, and xchandles, clearly aligning with the two major PoC components.
- Src Directory:
- Implements the CLI, drivers, layers, and primitives in Rust.
- The “layers” subdirectory clearly separates different business logic layers (e.g., action_layer, conditions_layer, precommit_layer, and verification_layer) which appear to coordinate with the Chialisp puzzles.
- The “primitives” subdirectory defines lower-level abstractions like catalog_registry, dig_reward_distributor, precommit_coin, etc.

##### Key Architectural Components & Their Relationships
a. Main Components:
- Command-Line Interface (CLI): Located in src/cli, this is the user interaction layer, handling inputs and triggering various blockchain operations.
- Business Logic Layers: Found in src/layers (e.g., action layers, conditions layer, precommit layer), these handle transaction coordination and orchestrate the underlying puzzles.
- Primitives: Located in src/primitives, these components define the fundamental data structures and logic (e.g., registration info, verification payments, NFT metadata).
- Chialisp Smart Contracts (Puzzles): Organized into puzzles/actions, puzzles/nft, puzzles/singleton, etc. These represent the on-chain logic, each addressing specific aspects of CATalog or XCHandles.
- Supporting Libraries: The include/ directory provides Chialisp libraries essential for functionalities such as secure NFT operations and SHA256 tree processing.
- CI/CD and Build Scripts: .github/workflows and build.sh are used for testing, building, and possibly deploying the system.

b. Relationships and Interactions:
- The CLI communicates with the underlying layers which then use the primitives to trigger appropriate smart contract actions in the puzzles.
- The action layers are closely tied to specific smart contracts (e.g., catalog registration, refund, dig operations, xchandles management) and interact with respective Chialisp puzzles.
- The DSL and utility libraries in include/ support both on-chain validations and cryptographic functions which are essential during contract execution.
- There is a clear separation between off-chain operations (CLI and Rust layers) and on-chain operations (puzzles in Chialisp).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is divided into distinct layers (CLI, business logic layers, primitives) and separate smart contracts, ensuring modularity.
- Layered Architecture: Rust layers handle user interaction, transaction orchestration, and validations before invoking the on-chain puzzles.
- Clear Domain Boundaries: Components for CATalog and XCHandles are clearly partitioned, with specialized folders in puzzles and corresponding modules in src.
- Use of Automation and Standardized Tools: The presence of CI configurations and build scripts emphasizes automated testing and deployment.

##### Final Detailed Suggestions
- Middle Layer: Business Logic Layers (src/layers and src/primitives), grouping the components by function (catalog, dig, xchandles, verification).
- Bottom Layer: On-chain Smart Contracts (puzzles directory) that execute the core blockchain operations.
- Relationships between CATalog and XCHandles components by showing how each module communicates with specific puzzles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Components
    subgraph "Off-chain Components"
        CLI("CLI Interface"):::offchain
        BL("Business Logic Layers"):::offchain
        PRIM("Primitives"):::offchain
        CLI -->|"triggers"| BL
        BL -->|"invokes"| PRIM
    end

    %% On-chain Components
    subgraph "On-chain Components"
        SC("Smart Contracts (Chialisp Puzzles)"):::onchain
        CB("Chia Blockchain"):::external
        PRIM -->|"executes"| SC
        SC -->|"deployedOn"| CB
    end

    %% Supporting Libraries
    LIB("Supporting Chialisp Libraries"):::onchain
    LIB ---|"provides"| SC

    %% Build & CI/CD Tools
    subgraph "Build & CI/CD"
        WORK("GitHub Workflows"):::ci
        BUILD("Build Script"):::ci
    end
    WORK ---|"triggersBuild"| BUILD
    BUILD ---|"builds"| CLI

    %% Click Events
    click CLI "https://github.com/yakuhito/slot-machine/tree/master/src/cli"
    click BL "https://github.com/yakuhito/slot-machine/tree/master/src/layers"
    click PRIM "https://github.com/yakuhito/slot-machine/tree/master/src/primitives"
    click SC "https://github.com/yakuhito/slot-machine/tree/master/puzzles"
    click LIB "https://github.com/yakuhito/slot-machine/tree/master/include"
    click WORK "https://github.com/yakuhito/slot-machine/tree/master/.github/workflows"
    click BUILD "https://github.com/yakuhito/slot-machine/blob/master/build.sh"

    %% Styles
    classDef offchain fill:#bbf,stroke:#333,stroke-width:2px;
    classDef onchain fill:#fdd,stroke:#333,stroke-width:2px;
    classDef external fill:#dfd,stroke:#333,stroke-width:2px;
    classDef ci fill:#ffc,stroke:#333,stroke-width:2px;
```
