# chiefwoods/splurge architecture

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

- Interactive diagram: https://gitdiagram.com/chiefwoods/splurge
- Repository: https://github.com/chiefwoods/splurge

## Overview

##### Main Components
- Frontend Application (Next.js App)
– Located in the “app” directory, this contains the Next.js pages (app/src/app), UI components (app/src/components and subdirectories), hooks, and other UI-related utilities.
– It handles routing (pages, dynamic routes for shoppers, stores, orders, etc.), state management, and user interactions.
– Uses libraries such as React, SWR for data fetching, and wallet-adapter for Solana wallet integration.
- On-chain Program (Solana Program)
– Found under the “programs/splurge” directory, it is written using Rust and Anchor.
– Contains various instructions (e.g., create_item, create_order, withdraw_earnings, etc.), state definitions, and utility functions.
– This is the backend “smart contract” that processes on-chain business logic.
- Blockchain and Ecosystem Layer
– The actual Solana blockchain is where on-chain transactions occur.
– External libraries and services (e.g., @solana/web3.js, @solana/spl-token, and external APIs like Helius) enable communication and transactions on-chain.
- Testing and Deployment Components
– “tests” directory holds functional tests (using Bun as the test runner) to simulate and verify actions performed by both the frontend and on-chain program.
– Configuration and deployment scripts (Anchor.toml, Cargo.toml, and migration scripts) help build and deploy the Solana program, while package.json and bun.lockb coordinate dependencies for the app.

##### Relationships & Data Flow
- User interactions on the frontend trigger API or direct blockchain calls using wallet adapters and Solana libraries.
- Data flows from the frontend’s UI components (including form dialogs and order management) to the blockchain via Solana web3 calls.
- The on-chain program listens for various instructions (e.g., create/store actions) and manipulates on-chain state accordingly.
- Tests simulate these interactions end-to-end by sending transactions and verifying state changes.

##### Architectural Patterns
- Separation of Concerns: Clear split between the user-facing Next.js frontend and the on-chain Solana backend.
- Modular Design: Both frontend and on-chain program are organized modularly (e.g., “app/src/components” for UI and “programs/splurge/src/instructions” for separate instructions).
- Use of Domain-Specific Frameworks: Anchor in the Rust program abstracts much of the on-chain logic into an easy-to-follow structure.

##### Technologies, Frameworks, & Libraries
- Frontend: Next.js, React, TypeScript, tailwind, and UI libraries (shadcn/ui).
- Blockchain & On-chain: Rust, Anchor, anchor-spl, and related crates.
- Communication: @solana/web3.js, wallet-adapter, and Solana-specific libraries.
- Testing: Bun is used as the test runner.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface (Frontend)"
        FE1["Pages & Routing"]:::frontend
        FE2["UI Components & Dialogs"]:::frontend
    end

    %% Business Logic / API & Wallet Layer
    subgraph "Business Logic / API & Wallet"
        BL1["Wallet Integration & Data Fetching"]:::frontend
    end

    %% On-chain Program Layer
    subgraph "On-chain Program (Smart Contract)"
        OCP1["Instructions"]:::onchain
        OCP2["State Definitions & Utilities"]:::onchain
    end

    %% Blockchain & External Services Layer
    subgraph "Blockchain & External Services"
        B1["Solana Blockchain"]:::blockchain
        B2["External Services (Helius & APIs)"]:::blockchain
    end

    %% Testing & Deployment Layer
    subgraph "Testing & Deployment"
        TD1["Tests (Bun)"]:::testing
        TD2["Anchor.toml"]:::testing
        TD3["Cargo.toml"]:::testing
    end

    %% Connections between layers
    FE1 -->|"userAction"| BL1
    FE2 -->|"userInteraction"| BL1
    BL1 -->|"initiateTxn"| OCP1
    OCP1 -->|"processTxn"| OCP2
    OCP1 -->|"sendTxn"| B1
    B1 -->|"confirmTxn"| OCP2
    OCP2 -->|"result"| BL1
    BL1 -->|"updateUI"| FE2

    %% External data flow
    BL1 -->|"fetchExternalData"| B2
    B2 -->|"response"| BL1

    %% Deployment & Testing relationships
    TD2 -->|"deployConfig"| OCP1
    TD3 -->|"deployConfig"| OCP2
    TD1 -->|"simulateFlows"| BL1

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef onchain fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef blockchain fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef testing fill:#F4A460,stroke:#000,stroke-width:2px;

    %% Click Events
    click FE1 "https://github.com/chiefwoods/splurge/tree/main/app/src/app"
    click FE2 "https://github.com/chiefwoods/splurge/tree/main/app/src/components"
    click OCP1 "https://github.com/chiefwoods/splurge/tree/main/programs/splurge/src/instructions"
    click OCP2 "https://github.com/chiefwoods/splurge/tree/main/programs/splurge/src/state"
    click TD1 "https://github.com/chiefwoods/splurge/tree/main/tests"
    click TD2 "https://github.com/chiefwoods/splurge/blob/main/Anchor.toml"
    click TD3 "https://github.com/chiefwoods/splurge/blob/main/Cargo.toml"
```
