# hatif03/movefwd-amm architecture

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

- Interactive diagram: https://gitdiagram.com/hatif03/movefwd-amm
- Repository: https://github.com/hatif03/movefwd-amm

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized application (dApp) comprising:
- On-chain Move smart contracts (AMM, NFT LP positions, fee logic, stable swap) deployed to the Sui blockchain.
- A Next.js 14 frontend (React, TypeScript) that interacts with those contracts via the Sui SDK and @mysten/dapp-kit.
- Shell scripts for contract deployment and demo workflows.
- Purpose: Provide a Uniswap-style AMM on Sui with NFT-based liquidity positions, multi-fee tiers, slippage protection, and a DeFi-styled UI.

##### File Structure Analysis
- contracts/ – Move smart contracts (sources/, tests/, Move.toml).
- sources/: module files organized by domain (constants, math, pool_factory, stable_swap_pool, lp_position_nft, fee_distributor, slippage_protection, events, errors, demo_tokens).
- tests/: unit & integration tests per module.
- frontend/ – Next.js app using the App Router.
- src/app/: page routes (dashboard, swap, pools, positions, faucet).
- src/components/: UI (shadcn/ui), layout, providers (Sui wallet context).
- src/lib/sui/: on-chain abstractions (constants, queries, transactions).
- scripts/ – deploy.sh (publish contracts), demo.sh (interactive demo).

##### README Insights
- Tech stack: Move language on Sui, Next.js, Tailwind CSS, @mysten/sui & dapp-kit, shadcn/ui, TanStack Query.
- Architecture described: constant product AMM, stable swap invariant, NFT LP positions, fee distributor, slippage protections.
- No off-chain database – all state lives on chain; UI pulls directly via RPC.

a. Main Components
- User Browser (React UI)
- Next.js Frontend (App Router, UI Components)
- Sui SDK & Dapp-Kit Layer (RPC client, tx builders, queries)
- Sui Wallet (user key management, transaction signing)
- Sui Testnet Full Node / RPC Endpoint
- Move Contracts on Sui (PoolFactory, StableSwapPool, LPPositionNFT, FeeDistributor, SlippageProtection, Math, Events, Errors)
- Shell Scripts (deploy.sh, demo.sh)
b. Relationships / Interactions
1. User interacts with React UI.
2. UI calls Sui SDK / dapp-kit to perform on-chain queries or build transactions.
3. Sui Wallet pops up for signature.
4. Signed tx hits Sui Testnet RPC.
5. RPC routes to Full Node, which executes Move contracts.
6. Move modules update on-chain state, emit events.
7. UI polls or listens for events/queries to update real-time data.
8. Scripts use Sui CLI to build, test, publish Move modules.
c. Architectural Patterns & Principles
- Modular Move contracts per domain (single responsibility).
- Layered architecture: UI → SDK/dapp-kit → RPC → Move modules.
- NFT as LP position for composability (extensibility).
- Fee distribution and slippage protection abstracted into dedicated modules.
d. Key Technologies
- Move & Sui Move framework
- Next.js 14 (App Router) & React
- @mysten/sui, @mysten/dapp-kit for blockchain interaction
- Tailwind CSS, shadcn/ui for styling
- TanStack Query for data fetching

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI Layer)" 
        direction TB
        UB["User Browser"]:::ui
        subgraph "Next.js Frontend" 
            direction TB
            LAYOUT["Layout"]:::ui
            DASHBOARD["Dashboard Page"]:::ui
            SWAP["Swap Page"]:::ui
            POOLS["Pools Page"]:::ui
            ADDPOOL["Add Pool Page"]:::ui
            POSITIONS["Positions Page"]:::ui
            FAUCET["Faucet Page"]:::ui
            subgraph "UI Components" 
                UICOMP["UI Components Library"]:::ui
                LAYCOMP["Layout Components"]:::ui
                SUIProv["Sui Wallet Provider"]:::ui
            end
        end
    end

    %% SDK Layer
    subgraph "SDK / dapp-kit Layer" 
        direction TB
        SDKIndex["index.ts"]:::sdk
        SDKConst["constants.ts"]:::sdk
        SDKQueries["queries.ts"]:::sdk
        SDKTx["transactions.ts"]:::sdk
    end

    %% Utilities
    UTIL["Utils & Mock Data"]:::sdk

    %% Wallet & RPC
    SWallet["Sui Wallet"]:::sdk
    RPC["Sui Testnet RPC Endpoint"]:::chain

    %% Blockchain Layer
    subgraph "Smart Contracts (Move Modules)" 
        direction TB
        PF["PoolFactory"]:::chain
        SSP["StableSwapPool"]:::chain
        LP["LPPositionNFT"]:::chain
        FD["FeeDistributor"]:::chain
        SP["SlippageProtection"]:::chain
        MATH["Math Library"]:::chain
        EVT["Events Module"]:::chain
        ERR["Errors Module"]:::chain
        CONS["Constants Module"]:::chain
        DEMO_TOK["Demo Tokens Module"]:::chain
    end

    %% Scripts
    subgraph "Scripts" 
        direction TB
        DEPLOY["deploy.sh"]:::scripts
        DEMO["demo.sh"]:::scripts
    end

    %% Explorer
    EXPLORER["Sui Explorer"]:::chain

    %% Connections
    UB -->|"interacts with"| LAYOUT
    LAYOUT -->|routes to| DASHBOARD
    LAYOUT -->|routes to| SWAP
    LAYOUT -->|routes to| POOLS
    LAYOUT -->|routes to| POSITIONS
    LAYOUT -->|routes to| FAUCET
    DASHBOARD -->|uses| SDKQueries
    SWAP -->|calls| SDKTx
    POOLS -->|queries| SDKQueries
    ADDPOOL -->|transactions| SDKTx
    POSITIONS -->|uses| SDKQueries
    FAUCET -->|calls| SDKTx
    UICOMP -->|styled by| LAYOUT
    LAYCOMP -->|composition| LAYOUT
    SUIProv -->|provides| SWallet

    SDKIndex -->|imports| SDKConst
    SDKIndex -->|imports| SDKQueries
    SDKIndex -->|imports| SDKTx
    SDKIndex -->|uses| UTIL

    SDKQueries -->|RPC calls| RPC
    SDKTx -->|builds tx| RPC
    RPMCall["RPC executes tx"]:::chain
    RPC -->|routes to| RPMCall
    RPMCall -->|executes| PF
    RPMCall -->|executes| SSP
    RPMCall -->|executes| LP
    RPMCall -->|executes| FD
    RPMCall -->|executes| SP
    RPMCall -->|calls library| MATH
    RPMCall -->|emits| EVT
    RPMCall -->|handles| ERR
    RPMCall -->|uses| CONS
    RPMCall -->|mints| DEMO_TOK

    EVT -->|view on| EXPLORER
    EXPLORER -->|reads state| RPC

    DEPLOY -->|"uses Sui CLI"| PF
    DEPLOY -->|"publishes"| SSP
    DEPLOY -->|"publishes"| LP
    DEMO -->|"runs demo"| DEMO_TOK

    %% Click Events - Frontend
    click LAYOUT "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/layout.tsx"
    click DASHBOARD "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/page.tsx"
    click SWAP "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/swap/page.tsx"
    click POOLS "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/pools/page.tsx"
    click ADDPOOL "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/pools/add/page.tsx"
    click POSITIONS "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/positions/page.tsx"
    click FAUCET "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/app/faucet/page.tsx"
    click UICOMP "https://github.com/hatif03/movefwd-amm/tree/main/frontend/src/components/ui/"
    click LAYCOMP "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/components/layout/header.tsx"
    click SUIProv "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/components/providers/sui-provider.tsx"
    click SDKConst "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/sui/constants.ts"
    click SDKQueries "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/sui/queries.ts"
    click SDKTx "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/sui/transactions.ts"
    click SDKIndex "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/sui/index.ts"
    click UTIL "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/utils.ts"
    click UTIL "https://github.com/hatif03/movefwd-amm/blob/main/frontend/src/lib/mock-data.ts"
    click DEPLOY "https://github.com/hatif03/movefwd-amm/blob/main/scripts/deploy.sh"
    click DEMO "https://github.com/hatif03/movefwd-amm/blob/main/scripts/demo.sh"

    %% Click Events - Blockchain
    click PF "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/pool_factory.move"
    click SSP "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/stable_swap_pool.move"
    click LP "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/lp_position_nft.move"
    click FD "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/fee_distributor.move"
    click SP "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/slippage_protection.move"
    click MATH "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/math.move"
    click EVT "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/events.move"
    click ERR "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/errors.move"
    click CONS "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/constants.move"
    click DEMO_TOK "https://github.com/hatif03/movefwd-amm/blob/main/contracts/sources/demo_tokens.move"
    click RPMCall "https://github.com/hatif03/movefwd-amm/tree/main/contracts/tests/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef sdk fill:#D0FFD0,stroke:#28a745,color:#22863a
    classDef chain fill:#F0D0FF,stroke:#6f42c1,color:#6f42c1
    classDef scripts fill:#E0E0E0,stroke:#586069,color:#586069
```
