# ayushmankoley/flipzy architecture

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

- Interactive diagram: https://gitdiagram.com/ayushmankoley/flipzy
- Repository: https://github.com/ayushmankoley/flipzy

## Overview

##### Project Type & Purpose
- Flipzy is a decentralized, full-stack coin-flip gambling dApp on the Aptos blockchain.
- Frontend: React + TypeScript + Vite UI that interacts with wallets and the blockchain.
- Backend: On-chain Move smart contract handling game logic, randomness, payouts.

##### Top-Level Components
A. Frontend Client
- React app (Vite + TS) under `/frontend`
- UI Components: game screens, headers, banners, message board, coin animation
- Wallet Integration: `WalletProvider.tsx`, aptos-wallet-adapter
- Utility Modules:
– `aptosClient.ts` and `surfClient.ts` for RPC/transaction calls
– ABIs: `coin_abi.ts`, `message_board_abi.ts`
– View-functions: e.g. `flipCoin.ts`, `getGameState.ts`
B. Smart Contract Layer
- Move modules under `/contract/sources/coinflip.move`
- Test suite: `/contract/tests/test_end_to_end.move`
- Scripts for compile/publish/test/upgrade under `/scripts/move`
C. Blockchain Infrastructure
- Aptos Network (Testnet/Mainnet)
- Aptos CLI for deployment
- GraphQL/RPC API endpoint
D. Deployment & CI/CD
- Netlify for frontend (`netlify.toml`, `_redirects`)
- npm scripts: build, dev, move:compile/test/publish/upgrade
E. Static Assets & Config
- Tailwind + Shadcn UI styling (`tailwind.config.js`)
- Env config (`.env`, VITE_ variables)

##### Relationships & Data Flows
1. User loads React app (Netlify CDN) → UI renders pages/components.
2. User connects wallet (via `WalletProvider`) → session established.
3. To display existing state, app calls view-functions against Aptos RPC or GraphQL.
4. On “Flip Coin” action:
- UI builds a transaction using client lib (aptosClient/surfClient) + ABI.
- Transaction is sent to user’s wallet → signed → broadcast to Aptos network.
5. Aptos validators process `flip_coin()` (or degen/whale) in Move contract → emit events.
6. Frontend listens or polls for events/state changes → updates RecentPlays feed + user balance.

##### Architectural Patterns & Principles
- Separation of concerns: UI layer vs. blockchain logic.
- Modular React components + utility hooks for reuse (ui/, components/, view-functions/).
- Scripted contract lifecycle: compile → test → deploy → upgrade.
- Env-driven configuration for testnet vs. mainnet.
- Event-driven updates via blockchain events or GraphQL subscriptions.

##### Final Checklist
[ ] Main components labeled
[ ] Key tech (React, Move, Netlify, Tailwind, Aptos CLI) called out
[ ] Notes on compile/test/deploy pipeline

## Diagram (Mermaid)

```mermaid
graph TD
    %% User & CDN
    User["User's Browser"]:::user
    CDN["Netlify CDN"]:::infra
    User --> CDN

    %% Frontend Client
    subgraph "Frontend Client (frontend/)" 
        ReactApp["Vite + React App"]:::frontend

        subgraph "Entry & Routing"
            Main["main.tsx"]:::frontend
            App["App.tsx"]:::frontend
            Router["router.tsx"]:::frontend
            Const["constants.ts"]:::frontend
        end

        subgraph "UI Components (frontend/components/)"
            AI["AccountInfo.tsx"]:::component
            CF["CoinFlipGame.tsx"]:::component
            HD["Header.tsx"]:::component
            LV["LabelValueGrid.tsx"]:::component
            MB["MessageBoard.tsx"]:::component
            NB["Navbar.tsx"]:::component
            NI["NetworkInfo.tsx"]:::component
            RP["RecentPlays.tsx"]:::component
            TB["TopBanner.tsx"]:::component
            TA["TransferAPT.tsx"]:::component
            WD["WalletDetails.tsx"]:::component
            WP["WalletProvider.tsx"]:::component
            WS["WalletSelector.tsx"]:::component
            WNA["WrongNetworkAlert.tsx"]:::component
        end

        subgraph "UI Primitives (frontend/components/ui/)"
            BTN["button.tsx"]:::ui
            CARD["card.tsx"]:::ui
            COLL["collapsible.tsx"]:::ui
            DLG["dialog.tsx"]:::ui
            DM["dropdown-menu.tsx"]:::ui
            INP["input.tsx"]:::ui
            LBL["label.tsx"]:::ui
            TST["toast.tsx"]:::ui
            TSTR["toaster.tsx"]:::ui
            UT["use-toast.ts"]:::ui
        end

        subgraph "Wallet & Clients (frontend/utils/)"
            AC["aptosClient.ts"]:::util
            SC["surfClient.ts"]:::util
            HLP["helpers.ts"]:::util
        end

        subgraph "ABIs (frontend/utils/)"
            ABI1["coin_abi.ts"]:::util
            ABI2["message_board_abi.ts"]:::util
        end

        subgraph "View-Functions (frontend/view-functions/)"
            VF1["flipCoin.ts"]:::vf
            VF2["getGameState.ts"]:::vf
            VF3["getAccountBalance.ts"]:::vf
            VF4["getMessageContent.ts"]:::vf
        end

        ReactApp --> Main
        ReactApp --> App
        ReactApp --> Router
        ReactApp --> Const
        ReactApp --> AI & CF & HD & LV & MB & NB & NI & RP & TB & TA & WD & WP & WS & WNA
        ReactApp --> BTN & CARD & COLL & DLG & DM & INP & LBL & TST & TSTR & UT
        ReactApp --> AC & SC & HLP
        ReactApp --> ABI1 & ABI2
        ReactApp --> VF1 & VF2 & VF3 & VF4
    end

    CDN --> ReactApp

    %% Blockchain API Layer
    subgraph "Blockchain API (Aptos RPC/GraphQL)"
        RPC["Aptos Full Node / RPC"]:::api
        GQL["GraphQL API"]:::api
    end

    ReactApp -->|"readViewFunction()"| RPC
    ReactApp -->|"readViewFunction()"| GQL

    %% Blockchain Network
    subgraph "Aptos Network"
        AptosNet["Testnet / Mainnet"]:::cloud
    end

    RPC --> AptosNet
    GQL --> AptosNet

    %% Smart Contract Layer
    subgraph "Smart Contract Layer (contract/)"
        CM["coinflip.move Module"]:::contract
        Events["On-chain State & Events"]:::contract
    end

    AptosNet -->|"deployModule() / sendTransaction()"| CM
    CM -->|"emitEvent()"| Events
    Events --> ReactApp

    %% Scripts & CI/CD
    subgraph "Scripts & CI/CD"
        NPM["package.json"]:::script
        NETL["netlify.toml"]:::config
        RED["_redirects"]:::config
        MSCR["scripts/move/"]:::script
    end

    %% Static Assets
    subgraph "Static Assets (public/icons/)"
        Won["won.mp3"]:::asset
        Lost["lost.mp3"]:::asset
    end

    %% Configurations
    subgraph "Build & Styling Configs"
        TWC["tailwind.config.js"]:::config
        VITEC["vite.config.ts"]:::config
        TSCFG["tsconfig.json & tsconfig.node.json & vite-env.d.ts"]:::config
    end

    %% Click Events
    click ReactApp "https://github.com/ayushmankoley/flipzy/tree/main/frontend/"
    click Main "https://github.com/ayushmankoley/flipzy/blob/main/frontend/main.tsx"
    click App "https://github.com/ayushmankoley/flipzy/blob/main/frontend/App.tsx"
    click Router "https://github.com/ayushmankoley/flipzy/blob/main/frontend/router.tsx"
    click Const "https://github.com/ayushmankoley/flipzy/blob/main/frontend/constants.ts"
    click AI "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/AccountInfo.tsx"
    click CF "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/CoinFlipGame.tsx"
    click HD "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/Header.tsx"
    click LV "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/LabelValueGrid.tsx"
    click MB "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/MessageBoard.tsx"
    click NB "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/Navbar.tsx"
    click NI "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/NetworkInfo.tsx"
    click RP "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/RecentPlays.tsx"
    click TB "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/TopBanner.tsx"
    click TA "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/TransferAPT.tsx"
    click WD "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/WalletDetails.tsx"
    click WP "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/WalletProvider.tsx"
    click WS "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/WalletSelector.tsx"
    click WNA "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/WrongNetworkAlert.tsx"
    click BTN "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/button.tsx"
    click CARD "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/card.tsx"
    click COLL "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/collapsible.tsx"
    click DLG "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/dialog.tsx"
    click DM "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/dropdown-menu.tsx"
    click INP "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/input.tsx"
    click LBL "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/label.tsx"
    click TST "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/toast.tsx"
    click TSTR "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/toaster.tsx"
    click UT "https://github.com/ayushmankoley/flipzy/blob/main/frontend/components/ui/use-toast.ts"
    click AC "https://github.com/ayushmankoley/flipzy/blob/main/frontend/utils/aptosClient.ts"
    click SC "https://github.com/ayushmankoley/flipzy/blob/main/frontend/utils/surfClient.ts"
    click HLP "https://github.com/ayushmankoley/flipzy/blob/main/frontend/utils/helpers.ts"
    click ABI1 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/utils/coin_abi.ts"
    click ABI2 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/utils/message_board_abi.ts"
    click VF1 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/view-functions/flipCoin.ts"
    click VF2 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/view-functions/getGameState.ts"
    click VF3 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/view-functions/getAccountBalance.ts"
    click VF4 "https://github.com/ayushmankoley/flipzy/blob/main/frontend/view-functions/getMessageContent.ts"
    click CM "https://github.com/ayushmankoley/flipzy/blob/main/contract/sources/coinflip.move"
    click Events "https://github.com/ayushmankoley/flipzy/blob/main/contract/tests/test_end_to_end.move"
    click MSCR "https://github.com/ayushmankoley/flipzy/tree/main/scripts/move/"
    click NETL "https://github.com/ayushmankoley/flipzy/blob/main/netlify.toml"
    click RED "https://github.com/ayushmankoley/flipzy/tree/main/frontend/_redirects"
    click NPM "https://github.com/ayushmankoley/flipzy/blob/main/package.json"
    click TWC "https://github.com/ayushmankoley/flipzy/blob/main/tailwind.config.js"
    click VITEC "https://github.com/ayushmankoley/flipzy/blob/main/vite.config.ts"
    click TSCFG "https://github.com/ayushmankoley/flipzy/blob/main/tsconfig.json"

    %% Styles
    classDef user fill:#B3E5FC,stroke:#0288D1
    classDef infra fill:#B3E5FC,stroke:#0288D1
    classDef frontend fill:#90CAF9,stroke:#1565C0
    classDef component fill:#BBDEFB,stroke:#1E88E5
    classDef ui fill:#E3F2FD,stroke:#1976D2
    classDef util fill:#FFF9C4,stroke:#F9A825
    classDef vf fill:#FFF59D,stroke:#F9A825
    classDef api fill:#C8E6C9,stroke:#388E3C
    classDef cloud fill:#B2DFDB,stroke:#00796B
    classDef contract fill:#A5D6A7,stroke:#2E7D32
    classDef script fill:#FFE0B2,stroke:#EF6C00
    classDef config fill:#CFD8DC,stroke:#455A64
    classDef asset fill:#FFF176,stroke:#FBC02D
```
