> For the complete documentation index, see [llms.txt](https://polymarks.gitbook.io/polymarks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polymarks.gitbook.io/polymarks-docs/technical-documentation/architecture.md).

# Architecture

PolyMarks follows a modular, feature-based architecture for scalability and maintainability.

## Project Structure

```
polymarks/
├── app/                    # Next.js App Router pages
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Homepage (3D landing)
│   ├── markets/           # Markets dashboard
│   ├── whales/            # Whale tracker
│   ├── outliers/          # Smart money signals
│   ├── market/[slug]/     # Individual market pages
│   └── api/               # API routes (proxies)
│       ├── markets/       # Polymarket markets proxy
│       └── trades/        # Polymarket trades proxy
├── core/                   # Shared utilities
│   ├── api/               # API clients
│   ├── config/            # Environment config
│   └── types/             # TypeScript types
├── features/               # Feature modules
│   ├── markets/           # Market listing & filtering
│   ├── whales/            # Whale tracking
│   ├── outliers/          # Smart money detection
│   ├── referral/          # Polymarket referral URLs
│   └── market-whale-sentiment/  # Market sentiment
├── components/            # Shared UI components
└── hooks/                 # Custom React hooks
```

## Design Principles

### 1. **Feature Modules**

Each feature is self-contained with:

* Types
* Business logic
* Components
* README documentation

Example: `features/whales/`

```
whales/
├── README.md              # Feature documentation
├── components/
│   ├── WhaleTradeCard.tsx
│   └── index.ts
├── lib/                   # Business logic (if needed)
└── index.ts               # Public API
```

### 2. **Core Module**

Shared utilities used across features:

* API clients (Polymarket, Helius)
* TypeScript types
* Environment configuration

### 3. **API Routes as Proxies**

Next.js API routes proxy external APIs to:

* Avoid CORS issues
* Hide API keys (server-side only)
* Add caching/rate limiting

Example: `/api/markets` → `gamma-api.polymarket.com/markets`

### 4. **Client vs Server Components**

* **Server Components:** Data fetching, initial render
* **Client Components:** Interactivity, real-time updates

## Data Flow

```
User Request
    ↓
Next.js Page (Server Component)
    ↓
API Route (/api/markets)
    ↓
External API (Polymarket)
    ↓
Transform Data (core/api clients)
    ↓
Feature Module (features/markets)
    ↓
UI Component
    ↓
User
```

## State Management

* **Server State:** React Server Components + `fetch` with caching
* **Client State:** React `useState` + `useEffect`
* **Real-Time:** Polling with `setInterval`

No external state library needed (keeping it simple).

## Performance Optimizations

1. **Next.js Caching:**
   * `next: { revalidate: 60 }` for markets (1 min cache)
   * `next: { revalidate: 30 }` for trades (30 sec cache)
2. **Incremental Static Regeneration (ISR):**
   * Markets dashboard pre-rendered
   * Revalidates in background
3. **API Rate Limiting:**
   * Removed market-specific whale fetching from grid
   * Only fetch on detail pages
   * Prevents 429/500 errors
4. **Lazy Loading:**
   * Three.js components lazy loaded
   * Heavy dependencies code-split