# fragmetric-labs/fragmetric-snapshot architecture

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

- Interactive diagram: https://gitdiagram.com/fragmetric-labs/fragmetric-snapshot
- Repository: https://github.com/fragmetric-labs/fragmetric-snapshot

## Overview

##### Project type and purpose
- This is an open-source CLI tool (TypeScript/Node.js) for taking on-chain DeFi “snapshots” on Solana.
- It exposes a single command (`snapshot`) with multiple pluggable “source” modules, each implementing logic to fetch and aggregate on-chain data via an RPC endpoint.

##### File structure
- Top-level files:
– index.js / index.ts: Entry point that wires up the CLI
– package.json / pnpm-workspace.yaml: Package configuration and workspace layout
– tsconfig.json, vitest.config.ts: Build/test configuration
- src/commands/snapshot:
– index.ts: Registers the `snapshot` command and handles global options (e.g. `--rpc`)
– output.ts: Formats and prints the result to stdout
- src/commands/snapshot/source:
– Each `<source>.ts` + `<source>.test.ts` pair implements a `SnapshotSource` interface
– `.idl.json`/`.idl.ts` files define on-chain account/data layouts for each protocol
– testutil.ts contains shared test helpers
- src/rpc.ts: RPC client abstraction for interacting with Solana nodes
- src/logger.ts: Simple logging utility

##### README for additional insights
- Shows usage patterns: `pnpx @fragmetric-labs/snapshot snapshot --rpc <URL> <source> <args…>`
- Lists supported sources (orca-liquidity, kamino-lending, etc.)
- Describes test and publish workflows

##### Main components & interactions
a. Component breakdown:
1. CLI Entrypoint
2. Command Registrar / Parser
3. Snapshot Command Handler
4. Source Module Factory & Loader
5. RPC Client Layer
6. Data Model / IDL Parsers
7. Output Formatter
8. Logger Utility
9. Test Harness (Vitest)
10. Build/Publish Pipeline (pnpm, build script, npm publish)
b. Relationships & data flow:
- User invokes `fragmetric-snapshot` CLI
→ Commander.js (or similar) parses arguments
→ Snapshot command handler picks the correct source module
→ Source module uses IDL definitions and the RPC client to fetch on-chain accounts
→ Business logic in the source aggregates `count` & `amount`
→ Handler passes result to Output Formatter → console (stdout)
→ Logger captures info/debug as configured
c. Architectural patterns / design principles:
- Plugin pattern for snapshot sources (extensibility)
- Single Responsibility per module (parser, source, RPC, logger, output)
- Interface-driven design for sources (`SnapshotSource` abstraction)
- Test-first development (Vitest unit tests alongside each source)
d. Key technologies:
- Node.js + TypeScript
- pnpm workspaces
- Commander.js (or similar) for CLI parsing
- Vitest for testing
- JSON-based IDL schemas for on-chain data layouts
- Solana RPC (helius for certain sources)

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI/UX Layer
    subgraph "CLI/UX Layer"
        direction TB
        CLIEntrypoint["CLI Entrypoint\n(src/index.ts, index.js)"]:::cli
        Parser["Command Registrar & Parser\n(src/commands/snapshot/index.ts)"]:::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Handler["Snapshot Command Handler\n(src/commands/snapshot/index.ts)"]:::business
        SourceFactory["Source Module Factory & Loader\n(src/commands/snapshot/source/index.ts)"]:::business
        subgraph "Source Modules"
            direction TB
            BanxLooping["banx-looping.ts"]:::business
            ExponentYieldTrading["exponent-yield-trading.ts"]:::business
            KaminoLending["kamino-lending.ts"]:::business
            KaminoLiquidity["kamino-liquidity.ts"]:::business
            LoopscaleLending["loopscale-lending.ts"]:::business
            LoopscaleLooping["loopscale-looping.ts"]:::business
            NxfinanceLooping["nxfinance-looping.ts"]:::business
            OrcaLiquidity["orca-liquidity.ts"]:::business
            RatexYieldTrading["ratex-yield-trading.ts"]:::business
            SandglassYieldTrading["sandglass-yield-trading.ts"]:::business
            SoonBridge["soon-bridge.ts"]:::business
            TextureLending["texture-lending.ts"]:::business
        end
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        IDLParsers["Data Model / IDL Parsers\n(json & ts files)"]:::data
        RPCClient["RPC Client\n(src/rpc.ts)"]:::data
        SolanaRPC["Solana RPC Endpoint"]:::external
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        OutputFormatter["Output Formatter\n(src/commands/snapshot/output.ts)"]:::util
        Logger["Logger Utility\n(src/logger.ts)"]:::util
        TestHarness["Test Harness\n(vitest.config.ts, src/commands/snapshot/source/testutil.ts, *.test.ts)"]:::util
    end

    %% Build & Deploy Layer
    subgraph "Build & Deploy"
        direction TB
        BuildPipeline["Build/Publish Pipeline\n(package.json, pnpm-workspace.yaml, tsconfig.json, vitest.config.ts)"]:::deploy
    end

    %% Data Flow
    CLIEntrypoint -->|"invoke CLI"| Parser
    Parser -->|"parse args[]"| Handler
    Handler -->|"select source"| SourceFactory
    SourceFactory -->|"load module"| BanxLooping
    SourceFactory --> ExponentYieldTrading
    SourceFactory --> KaminoLending
    SourceFactory --> KaminoLiquidity
    SourceFactory --> LoopscaleLending
    SourceFactory --> LoopscaleLooping
    SourceFactory --> NxfinanceLooping
    SourceFactory --> OrcaLiquidity
    SourceFactory --> RatexYieldTrading
    SourceFactory --> SandglassYieldTrading
    SourceFactory --> SoonBridge
    SourceFactory --> TextureLending

    BanxLooping -->|uses IDL| IDLParsers
    ExponentYieldTrading --> IDLParsers
    KaminoLending --> IDLParsers
    KaminoLiquidity --> IDLParsers
    LoopscaleLending --> IDLParsers
    LoopscaleLooping --> IDLParsers
    NxfinanceLooping --> IDLParsers
    OrcaLiquidity --> IDLParsers
    RatexYieldTrading --> IDLParsers
    SandglassYieldTrading --> IDLParsers
    SoonBridge --> IDLParsers
    TextureLending --> IDLParsers

    IDLParsers -->|"on-chain accounts"| RPCClient
    RPCClient -->|RPC calls| SolanaRPC

    Handler -->|"SnapshotResult"| OutputFormatter
    Handler --> Logger
    SourceFactory --> Logger
    RPCClient --> Logger

    TestHarness -->|tests modules| BanxLooping
    TestHarness -->|tests modules| OrcaLiquidity

    BuildPipeline --> CLIEntrypoint
    BuildPipeline --> Parser
    BuildPipeline --> Handler

    %% Click Events
    click CLIEntrypoint "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/index.ts"
    click Parser "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/index.ts"
    click Handler "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/index.ts"
    click OutputFormatter "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/output.ts"
    click SourceFactory "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/index.ts"
    click BanxLooping "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/banx-looping.ts"
    click ExponentYieldTrading "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/exponent-yield-trading.ts"
    click KaminoLending "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/kamino-lending.ts"
    click KaminoLiquidity "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/kamino-liquidity.ts"
    click LoopscaleLending "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/loopscale-lending.ts"
    click LoopscaleLooping "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/loopscale-looping.ts"
    click NxfinanceLooping "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/nxfinance-looping.ts"
    click OrcaLiquidity "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/orca-liquidity.ts"
    click RatexYieldTrading "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/ratex-yield-trading.ts"
    click SandglassYieldTrading "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/sandglass-yield-trading.ts"
    click SoonBridge "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/soon-bridge.ts"
    click TextureLending "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/texture-lending.ts"
    click RPCClient "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/rpc.ts"
    click Logger "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/logger.ts"
    click TestHarness "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/src/commands/snapshot/source/testutil.ts"
    click BuildPipeline "https://github.com/fragmetric-labs/fragmetric-snapshot/blob/main/package.json"

    %% Classes
    classDef cli fill:#bde0fe,stroke:#023047,color:#000;
    classDef business fill:#8ecae6,stroke:#0077b6,color:#000;
    classDef data fill:#ffb703,stroke:#fb8500,color:#000;
    classDef util fill:#adb5bd,stroke:#6c757d,color:#000;
    classDef deploy fill:#cdb4db,stroke:#9d4edd,color:#000;
    classDef external fill:#ffd166,stroke:#ef476f,color:#000;
```
