> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://polymarks.gitbook.io/polymarks-docs/technical-documentation/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.