# buffalojoec/arb-program architecture

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

- Interactive diagram: https://gitdiagram.com/buffalojoec/arb-program
- Repository: https://github.com/buffalojoec/arb-program

## Overview

##### Project type and purpose
- This is a full-stack Solana dApp for automated arbitrage trading:
- Frontend: Next.js/React UI (“app/” directory)
- On-chain program: Rust Solana program (“program/” directory)
- Test harness: TypeScript tests that bootstrap accounts and invoke the program (“tests/”)

##### File structure
- Top-level: monorepo with package.json, Cargo.toml, tsconfig.json
- app/
- Next.js config, pages/api, public assets, components, contexts, stores, Tailwind/CSS, IDL JSON
- UI lets user paste two swap program IDs, set concurrency & temperature, connect wallet and trigger bot
- program/
- Rust crate using solana_program (no Anchor)
- src/arb.rs, swap.rs, processor.rs, util.rs (partial deserialization)
- Single TryArbitrage instruction → nested loops → CPI to swap programs
- tests/
- main.test.ts: creates token accounts, airdrops, builds Address Lookup Table (ALT), sends TryArbitrage TXs
- util/: fixtures for assets, instructions

##### README for insights
- Architecture overview: UI → RPC Node → TX v0 with ALT → Arbitrage Program → CPI into two Swap Programs
- Preflight simulation: program errors on no-arbitrage, so client only pays fees on success
- Optimizations: bytemuck zero-copy, ALT to pack many accounts into one TX

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser / UI Layer"
        UI["Next.js UI"]:::frontend
        SDK["Client SDK & TX Builder"]:::frontend
    end

    rpc["Solana RPC Node / Cluster"]:::cloud
    ALT["Address Lookup Table (ALT)"]:::data
    TokenAccounts["Token Mints & Associated Token Accounts"]:::data

    subgraph "On-chain Arbitrage Program"
        arb["Arbitrage Program"]:::chain
        subgraph "Program Modules"
            entry["lib.rs\nEntry Point"]:::chain
            logic["arb.rs\nCore Logic"]:::chain
            cpi["swap.rs\nCPI Wrappers"]:::chain
            proc["processor.rs\nInstruction Processor"]:::chain
            state["partial_state.rs\nState Deser."]:::chain
            util["util.rs\nUtilities"]:::chain
            err["error.rs\nError Definitions"]:::chain
        end
    end

    subgraph "External Swap Programs"
        swap1["Swap Program #1"]:::chain
        swap2["Swap Program #2"]:::chain
    end

    subgraph "Test Harness"
        tests["Test Harness"]:::test
    end

    UI -->|"send TX v0\n(TryArbitrage, ALT ref, configs)"| rpc
    SDK -->|"build TX v0 with ALT"| rpc
    rpc -->|"resolve ALT"| ALT
    rpc -->|"submit TX"| arb
    ALT -->|"account list"| arb
    TokenAccounts -->|"read/write balances"| arb
    arb -->|"invoke CPI buy/sell"| swap1
    arb -->|"invoke CPI buy/sell"| swap2
    tests -->|"create ALT & fixtures\nsend TXs"| rpc

    click UI "https://github.com/buffalojoec/arb-program/tree/main/app/"
    click SDK "https://github.com/buffalojoec/arb-program/blob/main/app/src/utils/program.ts"
    click entry "https://github.com/buffalojoec/arb-program/blob/main/program/src/lib.rs"
    click logic "https://github.com/buffalojoec/arb-program/blob/main/program/src/arb.rs"
    click cpi "https://github.com/buffalojoec/arb-program/blob/main/program/src/swap.rs"
    click proc "https://github.com/buffalojoec/arb-program/blob/main/program/src/processor.rs"
    click state "https://github.com/buffalojoec/arb-program/blob/main/program/src/partial_state.rs"
    click util "https://github.com/buffalojoec/arb-program/blob/main/program/src/util.rs"
    click err "https://github.com/buffalojoec/arb-program/blob/main/program/src/error.rs"
    click swap1 "https://github.com/buffalojoec/arb-program/blob/main/app/src/idl/swap_program.json"
    click swap2 "https://github.com/buffalojoec/arb-program/blob/main/app/src/idl/swap_program.ts"
    click ALT "https://github.com/buffalojoec/arb-program/blob/main/tests/util/transaction.ts"
    click TokenAccounts "https://github.com/buffalojoec/arb-program/blob/main/tests/util/token.ts"
    click tests "https://github.com/buffalojoec/arb-program/blob/main/tests/main.test.ts"

    classDef frontend fill:#DCEEFB,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef chain fill:#FFE4C4,stroke:#D2691E,color:#D2691E,stroke-width:1px;
    classDef data fill:#E6FFED,stroke:#22863A,color:#22863A,stroke-width:1px,stroke-dasharray: 5 5;
    classDef cloud fill:#F0F0F0,stroke:#6A737D,color:#6A737D,stroke-width:1px,stroke-dasharray: 2 2;
    classDef test fill:#F5E6FF,stroke:#6f42c1,color:#6f42c1,stroke-width:1px;
```
