🏗 System Architecture

Overview

The DEX Dashboard is a full-stack Web3 monorepo with smart contracts on the backend (Solidity + Foundry) and a React frontend (Next.js 16 + wagmi). It simulates a decentralized exchange where users can mint mock tokens, trade them on a fixed-ratio DEX, and track market data from CoinGecko.

Monorepo Structure

DEX/
├── contracts/                     # Foundry smart contracts
│   ├── src/
│   │   ├── MockERC20.sol          # ERC20 token (mETH, mBTC, mUSDC)
│   │   ├── Faucet.sol             # Time-locked token faucet
│   │   └── MockDEX.sol            # Fixed-ratio DEX with 6 swap paths
│   ├── test/                      # 182+ Solidity tests
│   │   ├── MockERC20.t.sol        # 35 tests
│   │   ├── Faucet.t.sol           # 51 tests
│   │   ├── MockDEX.t.sol          # 96 tests (fuzz + invariant)
│   │   └── MockDEX.invariant.t.sol # Invariant tests
│   ├── script/
│   │   └── Deploy.s.sol           # Deployment script
│   ├── .env                       # Sepolia RPC URL + Etherscan API key
│   └── foundry.toml               # Foundry configuration
├── frontend/                      # Next.js 16 application
│   ├── src/
│   │   ├── app/                   # Pages (Home, Faucet, Swap, Analytics)
│   │   ├── components/            # UI components (shadcn/ui, custom)
│   │   ├── hooks/                 # Custom React hooks
│   │   ├── lib/                   # Constants, ABIs, utilities
│   │   └── providers.tsx          # Web3 provider
│   └── tests/                     # Vitest frontend tests
├── docs/                          # GitHub Pages documentation
│   ├── index.html                 # Documentation home
│   ├── user-guide/                # User-facing guides
│   ├── developer-guide/           # Developer-facing guides
│   ├── qa.html                    # FAQ page with search
│   └── assets/                    # CSS, JS
├── scripts/
│   └── update-addresses.sh        # Extracts deployed addresses → constants.ts
├── images/                        # README screenshots
└── Makefile                       # Build automation (install, build, test, deploy)

Smart Contract Architecture

Three contracts are deployed together. The deployment script handles the inter-contract wiring automatically.

Contract Dependencies

┌─────────────┐     ┌───────────────────┐
│  MockERC20  │────▶│      Faucet       │
│  (mETH)     │     │                   │
│             │     │  - mints via      │
│  MockERC20  │     │    setFaucet()    │
│  (mBTC)     │     │  - 24h cooldown   │
│             │     │  - 3 tokens       │
│  MockERC20  │     └───────────────────┘
│  (mUSDC)    │
│             │     ┌───────────────────┐
│             │────▶│     MockDEX       │
│             │     │                   │
│             │     │  - 3 reserves     │
│             │     │  - 2 swap rates   │
│             │     │  - 6 swap paths   │
│             │     │  - SafeERC20      │
│             │     └───────────────────┘
└─────────────┘

Deployment Flow

1. Step 1: Deploy 3 MockERC20 instances (mETH, mBTC, mUSDC) — each gets a placeholder faucet address
2. Step 2: Deploy Faucet contract — receives mETH, mBTC, mUSDC addresses; becomes their real faucet via setFaucet()
3. Step 3: Deploy MockDEX contract — receives all 3 token addresses plus initial swap rates (ethRate=1700, btcRate=40000)
4. Step 4: Add initial liquidity — owner deposits tokens into MockDEX reserves
5. Step 5: Update Faucet addresses — tokens' faucet is set to the real Faucet contract (after minting initial liquidity)

Data Flow

┌──────────┐    Connect Wallet     ┌─────────────┐
│  User    │──────────────────────▶│   MetaMask   │
│ (Browser)│                       │   (Wallet)   │
│          │◀──────────────────────│              │
│          │    Sign Txn / Read    └─────────────┘
└────┬─────┘                              │
     │                                    │
     │  ┌─────────────────────────────────┤
     │  │  wagmi / viem                   │
     │  │                                 │
     │  ├─ useAccount()                   │
     │  ├─ useReadContract()   ◀─── On-chain reads
     │  ├─ useWriteContract()  ───▶ On-chain writes
     │  └─ useWaitForTxnReceipt()
     │
     ▼
┌─────────────────────────────┐
│    Next.js 16 Frontend      │
│                             │
│  ┌───────────────────────┐  │
│  │  Pages (App Router)   │  │
│  │  ├─ Home (/)          │  │
│  │  ├─ Faucet /faucet    │  │
│  │  ├─ Swap /swap        │  │
│  │  └─ Analytics /analytics │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │  Custom Hooks         │  │
│  │  ├─ use-dex.ts        │  │
│  │  ├─ use-faucet.ts     │  │
│  │  ├─ use-token-balances│  │
│  │  ├─ use-analytics.ts  │  │
│  │  └─ use-market-data.ts│──▶ CoinGecko API
│  └───────────────────────┘  │
└─────────────────────────────┘

Read Path (Viewing Data)

1. User connects wallet via wagmi + MetaMask connector
2. Frontend calls useReadContract to fetch on-chain state (balances, reserves, rates, cooldowns)
3. Market data is fetched from CoinGecko API for candlestick charts and token prices
4. Analytics page combines on-chain DEX data with market data and simulated trade history

Write Path (Transactions)

1. User fills a form (e.g., swap amount on Swap page)
2. Frontend calls useWriteContract with the encoded function call
3. wagmi prompts the user to sign/confirm in MetaMask
4. Transaction is submitted to the network (Anvil or Sepolia)
5. Frontend waits for receipt via useWaitForTransactionReceipt
6. On success, queries are invalidated and refetched automatically

Frontend Component Architecture

layout/                components/                hooks/
├── header.tsx         ├── ui/ (13 primitives)    ├── use-dex.ts
├── footer.tsx         │   ├── button.tsx         ├── use-faucet.ts
└── wallet-button.tsx  │   ├── card.tsx           ├── use-token-balances.ts
                       │   ├── dialog.tsx         ├── use-analytics.ts
pages/                 │   ├── tabs.tsx           └── use-market-data.ts
├── page.tsx (Home)    │   └── ...
├── faucet/page.tsx    ├── home/                  lib/
├── swap/page.tsx      │   ├── stats-counters.tsx ├── constants.ts
└── analytics/         │   └── animated-section   ├── wagmi.ts
    ├── page.tsx       ├── faucet/                ├── dex-abi.ts
    └── client.tsx     │   └── claim-card.tsx     ├── faucet-abi.ts
                       ├── swap/                  ├── utils.ts
                       │   ├── swap-card.tsx      └── market-data.ts
                       │   └── settings.tsx
                       ├── analytics/
                       │   ├── stats-cards.tsx
                       │   ├── token-table.tsx
                       │   ├── trade-history.tsx
                       │   └── portfolio.tsx
                       └── charts/
                           └── candlestick.tsx

State Management

• Wallet state: wagmi hooks (useAccount, useBalance, useChainId)
• Contract reads: useReadContract / useReadContracts with automatic caching via @tanstack/react-query (10s stale time)
• Contract writes: useWriteContract + useWaitForTransactionReceipt — auto-invalidates queries on success
• Local state: React useState for form inputs, slippage settings, and UI toggles

Design Patterns

• Server/Client split: Pages are server components for metadata/SEO; interactive UI is delegated to client components
• Animated sections: AnimatedSection wraps content with Intersection Observer fade-in animations
• Error handling: Every component handles loading, error, empty, and not-deployed states
• Accessibility: Skip-to-content link, aria-labels, focus-visible styles, prefers-reduced-motion support
• Network detection: Frontend automatically detects Anvil vs Sepolia and shows correct contract addresses

Key Design Decisions

Decision	Rationale
Foundry (vs Hardhat)	Native Solidity testing with fuzz/invariant support, fast compilation in Rust, and built-in linting
Fixed-ratio DEX (vs AMM)	Educational simplicity — users understand rate-based swaps without AMM complexity (x⋅y=k). Rates are owner-set constants.
3-reserve model (vs 2-token pools)	Supports cross-rate swaps (mETH↔mBTC) by routing through mUSDC internally, demonstrating a real DeFi pattern
wagmi + viem	Modern, type-safe React hooks for wallet connection and contract interaction. Replaces ethers.js v5.
shadcn/ui + Tailwind	Accessible, customizable Radix UI primitives that compose well. Full design control without a bloated component library.
Raw HTML docs (GitHub Pages)	Zero build step, no framework dependencies. The docs are plain HTML/CSS/JS that deploy instantly via GitHub Pages.
--interactives 1 (private key)	Forge prompts for the private key interactively at deploy time. No env vars, no plaintext key files.

Testing Overview

The project has 182+ Solidity tests and frontend unit tests:

• MockERC20: 35 tests — minting, faucet restrictions, ownership, events
• Faucet: 51 tests — claims, cooldowns, edge cases, admin functions
• MockDEX: 96 tests — all 6 swap paths, slippage, liquidity, 14 fuzz tests, 4 invariant tests
• Frontend: Vitest + React Testing Library — utility functions, formatting helpers

See the Testing Guide for complete details.