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

# Architecture

> How the web app, API, judge worker, smart contracts, and subgraph fit together.

```
                       ┌────────────────────────┐
                       │       apps/web         │  Next.js 15 + Reown AppKit + HeroUI v3
        paste tweet →  │  /create  /m/[address] │
                       └─────────┬──────────────┘
                                 │ HTTP
                       ┌─────────▼──────────────┐
                       │       apps/api         │  Bun + Hono
   X post fetch via    │  /posts/evaluate       │  ├─ X-posts service (RapidAPI)
   twitter241,         │  /markets, /price/0g   │  ├─ gatekeeper (0G Compute TEE)
   CoinGecko 0G price  │  /users/:addr/positions│  └─ SQLite cache (proposals, posts, USD)
                       └─────────┬──────────────┘
                                 │ contract calls (viem)
                       ┌─────────▼──────────────┐
                       │  0G Chain (mainnet)    │  EVM, sub-second finality
                       │  MarketFactory ─────┬──┤  EIP-1167 clones
                       │  AIResolver         │  │  ECDSA-verifies TEE receipts
                       │  PredictionMarket × N  │  Parimutuel YES/NO
                       │     ├─ Treasury × N    │  ├─ reserve floor + adapter allowlist
                       │     └─ GimoAdapter × N │  └─ st0G liquid staking
                       └─────────▲──────────────┘
                                 │ submitResolution()
                       ┌─────────┴──────────────┐
                       │  apps/judge-worker     │  Bun cron worker
                       │  discover → judge      │  ├─ paginates factory
                       │  → sign → submit       │  ├─ judge runs in 0G Compute TEE
                       └────────────────────────┘  └─ signs domain-separated digest
```

## Process map

| Tier     | Process                  | Tech                                                             | Notes                                                                       |
| -------- | ------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Frontend | `signalium-web`          | Next.js 15, Reown AppKit, wagmi, viem, HeroUI v3, TanStack Query | Reads markets via API, places bets directly via wallet                      |
| Backend  | `signalium-api`          | Bun + Hono, SQLite (WAL)                                         | Caches X post metadata, AI proposals, 0G/USD price                          |
| Worker   | `signalium-judge-worker` | Bun cron                                                         | Sweeps factory for matured markets, runs judge in TEE, posts on-chain       |
| Indexer  | Goldsky subgraph         | AssemblyScript handlers                                          | Indexes factory + per-market events including yield snapshots               |
| Chain    | 0G mainnet (`16661`)     | EVM                                                              | Markets, treasuries, adapters; Gimo `StakePool` is a third-party dependency |

## Data flow at create-time

1. User pastes an X URL → `POST /posts/evaluate`.
2. API pulls the tweet (RapidAPI), runs the **gatekeeper** model (TEE) for an `eligible: bool` + score.
3. If eligible, the **writer** model drafts the proposal: `{ question, description, resolutionCriteria, resolutionDate, judgePrompt, aiProbability }`.
4. The judge prompt is uploaded to **0G Storage**; the API persists the proposal in SQLite keyed by the resulting merkle root.
5. The user reviews and signs `MarketFactory.createMarket(...)`. In one transaction the factory:
   * Clones a `PredictionMarket` (EIP-1167 minimal proxy).
   * Deploys a fresh `Treasury` whose `principal` is the new market.
   * Deploys a `GimoAdapter` wired to that Treasury.
   * Enables the adapter on the Treasury and hands ownership to the factory owner.
   * Initializes the market with the merkle root and the Treasury address.

## Data flow at resolve-time

1. Judge worker calls `startResolving()` on every market past `resolutionDate`.
2. For each market in `Resolving` status, it pulls the sealed prompt back from 0G Storage and runs the **judge** model in TEE.
3. The TEE provider signs `keccak256(abi.encode(DOMAIN_TAG, chainId, resolver, market, outcome, attestationHash, nonce))`.
4. Worker submits `AIResolver.submitResolution(market, outcome, attestationHash, proof)`.
5. `AIResolver` verifies the signature on-chain and forwards `resolve(outcome, attestationHash)` to the market.
6. The market recalls liquid funds from its Treasury and snapshots the 80/20 yield split.

See [Yield economics](/concepts/yield-economics) for the math behind step 6.