# props-labs/props-fuels architecture

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

- Interactive diagram: https://gitdiagram.com/props-labs/props-fuels
- Repository: https://github.com/props-labs/props-fuels

## Overview

##### Project type and purpose
- This is a monorepo (managed with pnpm + TurboRepo) for the “Props SDK,” a TypeScript/JavaScript library that enables minting NFTs on the Fuel blockchain.
- It bundles four major concerns:
- A core SDK library (`packages/props-fuels`)
- On-chain smart contracts written in Sway (`packages/sway-programs`)
- A reference/demo web app built with SvelteKit (`apps/demo-props-fuels`)
- Documentation site built with VitePress (`apps/docs`)
- The README describes the SDK’s goal: simplify NFT minting, editions, and built-in incentive mechanics via a high-level PropsSDK API that sits on top of `fuels`’ Provider & Wallet.

##### File structure
- Top-level meta/config: `pnpm-workspace.yaml`, `turbo.json`, build configs (`tsconfig.json`, `tsdoc.base.json`, `typedoc.json`), Bit metadata.
- `packages/props-fuels`: the core SDK package. Contains submodules for collections, editions, contracts, core, sway-api (ABI wrappers), utils, plus tests and build config (`tsup.config.ts`).
- `packages/sway-programs`: multiple Sway-based Fuel smart contracts (Collection, Edition, FeeSplitter, Registry) each with source (`.sw`) and Rust-based test harnesses.
- `apps/demo-props-fuels`: a SvelteKit frontend demo showcasing the SDK. Includes routes, components, styles, tests, and uses Vite.
- `apps/docs`: VitePress site generating API reference and guides (pulls from `apps/docs/api/*.md` generated by TypeDoc).
- `packages/scripts`: Node/TS scripts for automation (e.g., `create-edition.ts`).

##### Key insights from README
- High-level usage: instantiate `PropsSDK`, call methods like `editions.create()`.
- Relies on external `Provider` and `Wallet` from `fuels` to interact with the Fuel Testnet/Mainnet.
- Encourages a minimal code footprint for end-users.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        IDE["IDE & Terminal"]:::external
    end

    %% Monorepo Tooling
    subgraph "Monorepo Tooling"
        PNPM["pnpm-workspace.yaml"]:::tooling
        TURBO["turbo.json"]:::tooling
        TSCONFIG["tsconfig.json"]:::tooling
        TSDOC["tsdoc.base.json"]:::tooling
        TYPEDOC["typedoc.json"]:::tooling
    end

    IDE -->|uses| PNPM
    IDE -->|runs| TURBO
    IDE -->|references| TSCONFIG
    IDE -->|references| TSDOC
    IDE -->|references| TYPEDOC

    %% Core SDK Library
    subgraph "Core SDK (packages/props-fuels)" 
        PFS_INDEX["src/index.ts"]:::tsPackage
        PFS_COLLECTION["src/collection"]:::tsPackage
        PFS_EDITION["src/edition"]:::tsPackage
        PFS_CONTRACT_MGR["src/contract/contract-manager.ts"]:::tsPackage
        PFS_CORE["src/core"]:::tsPackage
        PFS_SWAY_API["src/sway-api"]:::tsPackage
        PFS_UTILS["src/utils"]:::tsPackage
        PFS_TSUP["tsup.config.ts"]:::tooling
        PFS_VITE["vite.config.ts"]:::tooling
    end

    PNPM -->|workspace| PFS_INDEX
    TURBO -->|builds| PFS_INDEX
    PFS_INDEX --> PFS_COLLECTION
    PFS_INDEX --> PFS_EDITION
    PFS_INDEX --> PFS_CONTRACT_MGR
    PFS_INDEX --> PFS_CORE
    PFS_INDEX --> PFS_SWAY_API
    PFS_INDEX --> PFS_UTILS

    click PFS_INDEX "https://github.com/props-labs/props-fuels/blob/main/packages/props-fuels/src/index.ts"
    click PFS_COLLECTION "https://github.com/props-labs/props-fuels/tree/main/packages/props-fuels/src/collection"
    click PFS_EDITION "https://github.com/props-labs/props-fuels/tree/main/packages/props-fuels/src/edition"
    click PFS_CONTRACT_MGR "https://github.com/props-labs/props-fuels/blob/main/packages/props-fuels/src/contract/contract-manager.ts"
    click PFS_CORE "https://github.com/props-labs/props-fuels/tree/main/packages/props-fuels/src/core"
    click PFS_SWAY_API "https://github.com/props-labs/props-fuels/tree/main/packages/props-fuels/src/sway-api"
    click PFS_UTILS "https://github.com/props-labs/props-fuels/tree/main/packages/props-fuels/src/utils"
    click PFS_TSUP "https://github.com/props-labs/props-fuels/blob/main/packages/props-fuels/tsup.config.ts"
    click PFS_VITE "https://github.com/props-labs/props-fuels/blob/main/packages/props-fuels/vite.config.ts"

    %% On-chain Smart Contracts
    subgraph "On-chain Contracts (packages/sway-programs)"
        SPP["Forc.toml & Cargo.toml"]:::tooling
        COL_CONTRACT["Props721Collection-contract/src/main.sw"]:::contract
        EDT_CONTRACT["Props721Edition-contract/src/main.sw"]:::contract
        FEE_CONTRACT["PropsFeeSplitter-contract/src/main.sw"]:::contract
        REG_CONTRACT["PropsRegistry-contract/src/main.sw"]:::contract
    end

    PNPM --> SPP
    TURBO --> SPP
    SPP --> COL_CONTRACT
    SPP --> EDT_CONTRACT
    SPP --> FEE_CONTRACT
    SPP --> REG_CONTRACT

    click COL_CONTRACT "https://github.com/props-labs/props-fuels/blob/main/packages/sway-programs/Props721Collection-contract/src/main.sw"
    click EDT_CONTRACT "https://github.com/props-labs/props-fuels/blob/main/packages/sway-programs/Props721Edition-contract/src/main.sw"
    click FEE_CONTRACT "https://github.com/props-labs/props-fuels/blob/main/packages/sway-programs/PropsFeeSplitter-contract/src/main.sw"
    click REG_CONTRACT "https://github.com/props-labs/props-fuels/blob/main/packages/sway-programs/PropsRegistry-contract/src/main.sw"

    %% Reference/Demo App
    subgraph "Demo App (apps/demo-props-fuels)"
        DEMO_CONFIG["svelte.config.js & vite.config.ts"]:::tooling
        DEMO_UI["src/lib/components"]:::tsPackage
        DEMO_ROUTES["+page.svelte/+layout.svelte"]:::tsPackage
        DEMO_UTILS["src/lib/utils"]:::tsPackage
        DEMO_TESTS["src/index.test.ts & tests"]:::tsPackage
    end

    IDE --> DEMO_CONFIG
    PNPM --> DEMO_CONFIG
    DEMO_UI -->|imports| PFS_INDEX
    DEMO_ROUTES -->|calls| PFS_INDEX
    DEMO_UTILS -->|uses| PFS_UTILS
    DEMO_TESTS -->|tests| DEMO_ROUTES

    click DEMO_CONFIG "https://github.com/props-labs/props-fuels/blob/main/apps/demo-props-fuels/svelte.config.js"
    click DEMO_CONFIG "https://github.com/props-labs/props-fuels/blob/main/apps/demo-props-fuels/vite.config.ts"
    click DEMO_UI "https://github.com/props-labs/props-fuels/tree/main/apps/demo-props-fuels/src/lib/components"
    click DEMO_ROUTES "https://github.com/props-labs/props-fuels/blob/main/apps/demo-props-fuels/src/routes/+page.svelte"
    click DEMO_ROUTES "https://github.com/props-labs/props-fuels/blob/main/apps/demo-props-fuels/src/routes/+layout.svelte"
    click DEMO_UTILS "https://github.com/props-labs/props-fuels/tree/main/apps/demo-props-fuels/src/lib/utils"
    click DEMO_TESTS "https://github.com/props-labs/props-fuels/blob/main/apps/demo-props-fuels/src/index.test.ts"

    %% Documentation Site
    subgraph "Documentation Site (apps/docs)"
        DOCS_CONFIG[".vitepress/config.js"]:::tooling
        DOCS_API["api (TypeDoc output)"]:::tsPackage
        DOCS_GUIDES["collections, editions, incentives"]:::tsPackage
        DOCS_SERVER["server.js"]:::tooling
    end

    IDE --> DOCS_CONFIG
    PNPM --> DOCS_CONFIG
    DOCS_API -->|generates from| PFS_INDEX
    DOCS_GUIDES -->|documents| PFS_COLLECTION & PFS_EDITION
    DOCS_SERVER -->|serves| DOCS_API & DOCS_GUIDES

    click DOCS_CONFIG "https://github.com/props-labs/props-fuels/blob/main/apps/docs/.vitepress/config.js"
    click DOCS_API "https://github.com/props-labs/props-fuels/tree/main/apps/docs/api"
    click DOCS_GUIDES "https://github.com/props-labs/props-fuels/tree/main/apps/docs/collections"
    click DOCS_GUIDES "https://github.com/props-labs/props-fuels/tree/main/apps/docs/editions"
    click DOCS_GUIDES "https://github.com/props-labs/props-fuels/tree/main/apps/docs/incentives"
    click DOCS_SERVER "https://github.com/props-labs/props-fuels/blob/main/apps/docs/server.js"

    %% Automation Scripts & CI
    subgraph "Automation & CI (packages/scripts)"
        SCRIPTS_CREATE["create-edition.ts"]:::script
        SCRIPTS_CFG["tsconfig.json & package.json"]:::tooling
    end

    IDE --> SCRIPTS_CREATE
    TURBO --> SCRIPTS_CREATE
    SCRIPTS_CREATE -->|uses| PFS_EDITION
    click SCRIPTS_CREATE "https://github.com/props-labs/props-fuels/blob/main/packages/scripts/create-edition.ts"
    click SCRIPTS_CFG "https://github.com/props-labs/props-fuels/blob/main/packages/scripts/tsconfig.json"

    %% External Services
    subgraph "External Services"
        FUEL_NODE["Fuel Nodes RPC"]:::external
        NPM_REG["NPM Registry"]:::external
        VERCEL["Vercel Hosting"]:::external
    end

    PFS_INDEX -->|publishes| NPM_REG
    DEMO_ROUTES -->|requests RPC| FUEL_NODE
    PFS_CONTRACT_MGR -->|sends TX| FUEL_NODE
    FUEL_NODE -->|executes| COL_CONTRACT
    FUEL_NODE -->|executes| EDT_CONTRACT
    FUEL_NODE -->|executes| FEE_CONTRACT
    FUEL_NODE -->|executes| REG_CONTRACT
    DOCS_CONFIG -->|deploys| VERCEL

    %% Styles
    classDef tsPackage fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef contract fill:#E8FFEA,stroke:#2F8F2F,color:#2F8F2F;
    classDef tooling fill:#FFF4D0,stroke:#D69D00,color:#D69D00;
    classDef external fill:#FFE8D0,stroke:#D66A00,color:#D66A00;
    classDef script fill:#F0D0FF,stroke:#9B4F9B,color:#9B4F9B;
```
