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

# Architecture

# Predicta System Architecture 🧠

**Cortex Engine, Hedgehog (Risk), and Mimic (Social) Integration**

> **Overview**: Predicta is an autonomous intelligence layer for decentralized prediction markets. It combines AI-driven alpha generation (Cortex), automated risk management (Hedgehog), and community-driven copying (Mimic).

***

## 1. Core Ecosystem Components

| Layer            | Component                   | File / Contract              | Role                                                 |
| ---------------- | --------------------------- | ---------------------------- | ---------------------------------------------------- |
| **Intelligence** | **Cortex Brain**            | `cortex/alpha.py`            | 7-factor market analysis (E1-E7)                     |
| **Execution**    | **Trader Bot**              | `cortex/cortex_trader.py`    | Autonomous portfolio manager                         |
| **Risk**         | **Hedgehog (Hedge Engine)** | `cortex/hedge_adapter.py`    | Delta-neutral hedging via perps (SynFutures/ZEUS)    |
| **Social**       | **Mimic Mode**              | `cortex/mimic_relay.py`      | Multi-user copy trading orchestration                |
| **Persistence**  | **Personal Vaults**         | `contracts/PreonVault.sol`   | ERC-4626 personal trading accounts                   |
| **Treasury**     | **Yield Gateway**           | `contracts/YieldGateway.sol` | Lending integration (Moonwell) for self-funding bets |

***

## 2. Integrated System Map

```mermaid theme={null}
graph TD
    subgraph Users [User Layer]
        U[Follower] -->|Mimic| V[PreonVault]
        Leader[Leader] -->|Trade Signal| Relay
    end

    subgraph Intelligence [Cortex Brain - System 2]
        A[Market Data] -->|Analyze| B(alpha.py)
        B -->|E1-E7 Scoring| C{Decision Gate}
    end

    subgraph Social_Execution [Mimic Relay]
        Relay[mimic_relay.py] -->|Calculate Shares| V
        V -->|Trade| Core[PredictaCoreV2]
    end

    subgraph Autonomous_Execution [Cortex Trader - System 3]
        C -->|BUY| Agent[cortex_trader.py]
        Agent -->|Place Bet| Core
        Agent -->|Trigger| Hedge[hedge_adapter.py]
        Hedge -->|Short Perp| SynFutures[Perp Protocol]
    end

    Core -->|On-Chain State| Base[Base Blockchain]
```

***

## 3. Key Subsystems

### 3.1 The Cortex Brain (System 2)

The "Analyst" layer that scores markets from 0 to 1 based on:

* **E1 - Theta**: Time decay.
* **E2 - Depth**: Order book liquidity.
* **E4 - AI Prob**: Domain-aware ML prediction (Crypto/Sports/Politics).
* **E5 - Delusion**: Market price vs. AI conviction.
* **E7 - Sentiment**: News and social analytics.

### 3.2 Hedgehog (The Hedge Engine)

Aims for **delta-neutrality**. When Cortex takes a directional bet on a crypto market (e.g., "BTC > \$100k"), Hedgehog automatically opens an offsetting short position on a perpetual exchange (SynFutures or ZEUS).

### 3.3 Mimic Mode (The Social Relay)

Leverages Farcaster social signals.

* **Signal**: A Leader places a trade.
* **Relay**: The `mimic_relay.py` service detects the signal.
* **Execution**: The relay triggers mirror trades for all followers via their individual `PreonVault` contracts.

### 3.4 Yield Gateway & Preon Vaults

Predicta's treasury management system:

* **Personal Vaults**: Each user (or mimic relationship) has a dedicated vault that holds PUSD.
* **Yield Generation**: Idle funds in vaults can be routed through the `YieldGateway` to Moonwell to earn interest, which can then be used to fund "Risk-Free" micro-bets.

### 3.5 Identity & Simulation (V2)

* **Privy**: Non-custodial identity provider supporting Email, Social, and Web3 logins.
* **Embedded Wallets**: Privy-managed MPC EOAs serve as the signers for Smart Accounts.
* **Simulation Bypass**: A headless authentication mechanism for `persona-sim` agents using deterministic tokens derived from a shared secret.

***

## 4. Technical Stack

* **Blockchain**: Base (Ethereum L2)
* **Identity**: Privy (Non-custodial, Social + Email + Wallet)
* **Account Abstraction**: ERC-4337 (Pimlico / Coinbase CDP Paymaster)
* **Smart Contracts**: Solidity (Foundry)
* **Backend**: Python (FastAPI, Web3.py) & Node.js (Next.js Server Actions)
* **Frontend**: Next.js 15, Tailwind CSS, Lucide React
* **Data**: Firestore (Real-time sync), Polymarket API (Gamma/CLOB)

***

## 5. Directory Structure

```text theme={null}
├── contracts/          # Smart Contracts (Foundry)
├── cortex/             # AI & Backend Services (Python)
│   ├── alpha.py        # Brain logic
│   ├── hedge_adapter.py# Risk management
│   └── mimic_relay.py  # Copy trading
├── functions/          # Firebase Cloud Functions (Node.js)
├── persona-sim/        # QA & Persona Simulation Engine
├── src/                # Frontend Application (Next.js)
│   ├── components/     # React UI components
│   └── lib/auth/       # Unified Identity (Privy)
└── docs/               # Technical Documentation
```