⚛ Frontend Architecture

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS v4 + shadcn/ui
• Wallet: wagmi v2 + viem
• Charts: Custom SVG candlestick charts + CoinGecko API
• Icons: Lucide React
• State: React Query (@tanstack/react-query)

Project Structure

frontend/src/
├── app/                    # App Router pages
│   ├── layout.tsx          # Root layout (header, footer, providers)
│   ├── page.tsx            # Home page with hero, features, stats
│   ├── not-found.tsx       # Custom 404 page
│   ├── faucet/page.tsx     # Faucet claim interface
│   ├── swap/page.tsx       # Swap trading interface
│   └── analytics/          # Analytics dashboard
│       ├── page.tsx        # Server component (metadata + layout)
│       └── analytics-client.tsx  # Client component (data + charts)
├── components/             # Shared UI components
│   ├── ui/                 # shadcn/ui primitives (13 components)
│   ├── layout/             # Header, Footer, WalletButton
│   ├── home/               # StatsCounters, AnimatedSection
│   ├── faucet/             # FaucetClaimCard, FaucetAnalytics
│   ├── swap/               # SwapCard, SlippageSettings, LiquidityInfo
│   ├── analytics/          # StatsCards, TokenStatsTable, TradeHistoryTable, PortfolioOverview
│   └── charts/             # CandlestickChart, MarketStats
├── hooks/                  # Custom React hooks
│   ├── use-dex.ts          # DEX contract interactions
│   ├── use-faucet.ts       # Faucet contract interactions
│   ├── use-token-balances.ts  # Token balance queries
│   ├── use-analytics.ts    # Analytics data (simulated + on-chain)
│   └── use-market-data.ts  # CoinGecko market data
└── lib/                    # Utilities and constants
    ├── constants.ts        # Contract addresses, token metadata
    ├── wagmi.ts            # wagmi configuration
    ├── market-data.ts      # CoinGecko API client
    ├── dex-abi.ts          # DEX + ERC20 ABIs
    ├── faucet-abi.ts       # Faucet ABI
    └── utils.ts            # cn() utility (tailwind-merge + clsx)

State Management

• Wallet: wagmi hooks (useAccount, useBalance, useChainId)
• Contract reads: useReadContract, useReadContracts (wagmi)
• Contract writes: useWriteContract + useWaitForTransactionReceipt
• Caching: @tanstack/react-query (configured with 10s stale time)
• Local state: React useState for form inputs and UI state

Component Patterns

• Server/Client split: Pages are server components; interactive UI is in client components
• Animated sections: AnimatedSection wraps content with Intersection Observer fade-in
• Error handling: Every component handles loading, error, empty, and not-deployed states
• Accessibility: Skip-to-content link, aria-labels, focus-visible styles, reduced-motion support