> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mouth.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> High-level technical architecture of the Mouth protocol.

## System Architecture

```mermaid theme={null}
graph TB
    subgraph "User Layer"
        XApp[X / Twitter]
        WebApp[Mouth Web App]
    end

    subgraph "Backend Services"
        Bot[X Bot Service]
        API[Mouth API]
        RE[Resolution Engine]
        Indexer[Event Indexer]
    end

    subgraph "Identity & Wallet"
        Privy[Privy SDK]
        EW[Embedded Wallets]
    end

    subgraph "Base (L2)"
        Factory[MouthBetFactory]
        Bets[Bet Contracts]
        USDC[USDC on Base]
    end

    subgraph "External"
        Oracles[Chainlink / Pyth]
        XApi[X API]
    end

    XApp -->|tag @Mouth_App| Bot
    Bot -->|replies, notifications| XApp
    Bot -->|reads/writes| API
    WebApp -->|user actions| API
    WebApp -->|auth, wallet| Privy
    Privy -->|creates| EW
    API -->|deploy, deposit, resolve| Factory
    Factory -->|creates| Bets
    EW -->|USDC transfers| Bets
    RE -->|resolve bets| Bets
    RE -->|price data| Oracles
    Bot -->|tweets, reads| XApi
    Indexer -->|listens to events| Bets
    Indexer -->|updates| API
```

## Components

### Frontend: Mouth Web App

* **Framework**: Next.js (App Router)
* **Auth & Wallets**: Privy SDK
* **Styling**: Tailwind CSS
* **State management**: React Query for server state
* **Key pages**:
  * `/` — Landing page + explore active bets
  * `/create` — Create a new bet
  * `/bet/[id]` — Bet detail page (view, accept, claim)
  * `/@[handle]` — User profile page
  * `/leaderboard` — Global leaderboard

### Backend: Mouth API

* **Runtime**: Node.js
* **Framework**: Express or Hono
* **Database**: PostgreSQL (bet metadata, user profiles, X handles)
* **Key responsibilities**:
  * User registration and X handle mapping
  * Bet CRUD operations (off-chain metadata)
  * Serve data to the web app (bet lists, profiles, leaderboard)
  * Trigger smart contract interactions via server-side Privy wallets

### X Bot Service

* **Runtime**: Node.js (standalone service)
* **X API**: v2 (filtered stream or polling for mentions)
* **Key responsibilities**:
  * Monitor `@Mouth_App` mentions
  * Parse tweet text with Claude Haiku to extract challenge parameters
  * Create draft challenges in `draft_challenges` table
  * Post challenge links and lifecycle notifications

### Resolution Engine

* **Runtime**: Node.js (cron-based or event-driven)
* **Key responsibilities**:
  * Monitor bets approaching expiration
  * Fetch data from oracles for automatic resolution
  * Queue manual resolutions for the Mouth team
  * Submit resolution transactions to smart contracts
  * Manage dispute windows

### Event Indexer

* **Options**: Custom indexer, Envio, or The Graph subgraph
* **Key responsibilities**:
  * Listen to on-chain events from bet contracts (BetCreated, BetAccepted, BetResolved, FundsClaimed)
  * Update the database in real-time
  * Ensure the web app reflects the latest on-chain state

### Smart Contracts (Base)

* **MouthBetFactory**: Deploys individual bet contracts
* **MouthBet**: Individual bet escrow contract (holds USDC, enforces rules)
* **Language**: Solidity ^0.8.24
* **USDC**: Native USDC on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)

See [Smart Contracts](/smart-contracts/overview) for detailed contract architecture.

## Data Flow

### Bet Creation

1. User authenticates via Privy (X login → embedded wallet)
2. User fills bet form on web app
3. API stores off-chain metadata (description, tweet URL, category)
4. API triggers Factory contract to deploy a new Bet contract
5. User's embedded wallet deposits USDC into the Bet contract
6. Indexer picks up `BetCreated` event, updates database
7. Bot posts on X (if applicable)

### Bet Resolution

1. Resolution Engine detects bet has reached expiration
2. For auto-resolution: fetches oracle data, determines outcome
3. For manual resolution: flags for Mouth team review
4. Resolution is submitted to the Bet contract via `resolve()`
5. **If disputeable**: 48-hour dispute window starts → `finalize()` after window expires
6. **If non-disputeable**: bet is immediately finalized
7. Indexer picks up `Resolved` / `Finalized` events
8. Bot posts result on X
9. For non-disputeable PvP 1v1: backend calls `resolverClaim()` to distribute funds automatically
10. For disputeable / Open PvP: winner claims via web app → USDC sent to embedded wallet