# mahhheshh/solapet-capstone architecture

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

- Interactive diagram: https://gitdiagram.com/mahhheshh/solapet-capstone
- Repository: https://github.com/mahhheshh/solapet-capstone

## Overview

##### Project Type and Purpose
- This is a Solana-based blockchain game built using the Anchor framework (note the presence of Anchor.toml and Rust Cargo projects).
- The project—named “solapet-capstone”—centers on managing an NFT-based pet game. It lets players deposit NFTs representing pets, perform interactions (feed, bathe), and engage in pet duels. It also includes admin functions for game configuration and fee management.

##### Analyzing the File Structure
- Top-Level Organization:
- The root contains configuration files (Cargo.toml, Anchor.toml, package.json, tsconfig.json, etc.), which indicate the project uses both Rust (for the on-chain program) and TypeScript (for deployments/migrations and tests).
- The “programs/solapet-capstone” directory is where the main smart contract resides.
- Within programs/solapet-capstone:
- The “src” directory is organized into logical modules:
- “instructions” – This contains separate Rust modules for each action (e.g., deposit_nft, withdraw_nft, init_config, pet duel actions, etc.).
- “state” – This holds modules describing the on-chain state (e.g., game_config, pet_duel, pet_stats).
- “helper” – For supplementary functionality like signature verification and generating numbers.
- Migrations and tests directories indicate integration/scripts to deploy and verify the contract functionality.

##### Key Insights from the README
- It clearly distinguishes between Admin Actions (such as initializing game configuration, managing PDAs for config and vault, and updating fees) and Player Actions (actions like depositing/withdrawing NFT, pet interactions, starting and engaging in pet duels).
- The README outlines specific Program-Derived Addresses (PDAs) for configuration, pet stats, and pet duels. These PDAs are essential on-chain accounts used to manage game state.
- The instructions describe the lifecycle of interactions: initializing game state, depositing NFTs, handling pet interactions, and managing pet duels.

##### Main Components
a. Client/Interface Components:
- Player Clients: Wallet interfaces or dApps that trigger actions like deposit_nft, withdraw_nft, pet_interaction, init_pet_duel, accept_pet_duel, and pet_attack.
- Admin Interfaces: Tools (possibly a CLI or dApp) used to call administrative actions (initialize_game_config, update_fees).

b. On-Chain Program Component:
- Solapet Capstone Program: Represent this as a central module that encapsulates all instructions.
- Instruction Handlers: Separate calls for deposit, withdrawal, pet duel initiation, etc.
- State Modules: game_config PDA, pet_stats PDA, pet_duel PDA that store persistent state.
- Helper Utilities: Modules for signature verification and generating random numbers for in-game dynamics.

c. Supporting Systems:
- Game Vault: An on-chain account (linked with config and PDAs) that holds game funds (fees, rewards).
- Interaction with the token/NFT program: Show how NFT transfers are executed when depositing or withdrawing an NFT.

d. Data Flow and Relationships:
- How the admin actions impact the configuration and fee setups.
- A channel showing how NFT assets are moved between the player’s associated token account and the game’s vault account.

##### Architectural Patterns and Design Principles
- Modularization: Separate “instructions” and “state” clearly define how the business logic is structured—close to an MVC-like separation where instructions act as controllers modifying the state models.
- Client/Server (or Client/Smart Contract) segregation: Distinguish the off-chain components (clients, migrations, tests) from the on-chain logic.
- Layered approach: At the top, the external interfaces (Players & Admins) interact with the blockchain program, which delegates work to its internal modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        A1["Admin Client"]:::client
        P1["Player Client"]:::client
    end

    %% External Systems
    subgraph "External Systems"
        NFT["NFT Token Program"]:::external
        Vault["Game Vault PDA"]:::state
    end

    %% On-Chain Program Components
    subgraph "On-Chain Program"
        SCP["Solapet Capstone Program"]:::onchain
        IH["Instruction Handlers"]:::instruction
        subgraph "State Modules"
            GC["Game Config PDA"]:::state
            PD["Pet Duel PDA"]:::state
            PS["Pet Stats PDA"]:::state
        end
        subgraph "Helper Utilities"
            GN["Random Number Generator"]:::helper
            VS["Signature Verification"]:::helper
        end
    end

    %% Deployment & Testing
    subgraph "Deployment & Testing"
        DS["Deployment Scripts"]:::deployment
        IT["Integration Tests"]:::deployment
    end

    %% Relationships
    A1 -->|"calls_Admin_actions"| IH
    P1 -->|"calls_Player_actions"| IH
    IH -->|"updates_state"| GC
    IH -->|"updates_state"| PD
    IH -->|"updates_state"| PS
    IH -->|"calls_validation"| GN
    IH -->|"calls_validation"| VS
    P1 -->|"triggers_NFT_deposit"| NFT
    NFT -->|"transfers_asset"| Vault
    IH -->|"manages_vault"| Vault
    A1 -->|"configures_game"| GC
    A1 -->|"updates_fees"| Vault
    DS -->|"deploys"| SCP
    IT -->|"tests_program"| SCP

    %% Click Events
    click SCP "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/lib.rs"
    click IH "https://github.com/mahhheshh/solapet-capstone/tree/main/programs/solapet-capstone/src/instructions/"
    click GC "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/state/game_config.rs"
    click PD "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/state/pet_duel.rs"
    click PS "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/state/pet_stats.rs"
    click GN "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/helper/gen_number.rs"
    click VS "https://github.com/mahhheshh/solapet-capstone/blob/main/programs/solapet-capstone/src/helper/verify_sig.rs"
    click DS "https://github.com/mahhheshh/solapet-capstone/blob/main/migrations/deploy.ts"
    click IT "https://github.com/mahhheshh/solapet-capstone/blob/main/tests/solapet-capstone.ts"

    %% Styles
    classDef client fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef onchain fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef instruction fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef state fill:#87CEFA,stroke:#000,stroke-width:1px;
    classDef helper fill:#DA70D6,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5,5;
    classDef deployment fill:#F5DEB3,stroke:#000,stroke-width:1px;
```
