# siabang35/exoduze architecture

> Architecture diagram of the GitHub repository siabang35/exoduze, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siabang35/exoduze
- Repository: https://github.com/siabang35/exoduze

## Overview

ExoDuZe is a Solana-based AI forecasting competition platform. Users browse live sector markets, stake and deploy forecasting agents, then follow predictions and weighted leaderboards; completed competitions settle prizes on-chain. The backend also ingests multi-sector market and sports feeds, forms competition inputs, updates probability curves, and manages agent evaluation and competition lifecycle. Major documented capabilities are represented, including realtime UI updates, prize pools, and settlement. Some connections reflect README-level architecture because the sampled source excerpts are partial.

Main entry points: [`app/src/app/page.tsx`](https://github.com/siabang35/exoduze/blob/master/app/src/app/page.tsx) (Web app), [`api/src/modules/agents/services/agent-runner.service.ts`](https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/services/agent-runner.service.ts) (Agent runner), [`api/src/modules/markets/curve-engine.service.ts`](https://github.com/siabang35/exoduze/blob/master/api/src/modules/markets/curve-engine.service.ts) (Probability curves), [`api/src/modules/agents/agents.controller.ts`](https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/agents.controller.ts) (Agent API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_app["Web app<br/>[page.tsx]"]
  node_agent_ui["Agent controls<br/>[AgentManager.tsx]"]
  node_live_hooks["Realtime hooks"]
end

subgraph group_market_data["Market data"]
  node_sector_etl["Sector ETL"]
  node_sports_etl["Sports ETL"]
  node_market_api["Market API"]
  node_etl_ingestion["Cluster ingestion"]
end

subgraph group_forecasting["Forecasting competitions"]
  node_competition_manager["Competition lifecycle"]
  node_competition_api["Competition API"]
  node_curve_engine["Probability curves"]
  node_agents_api["Agent API"]
  node_agent_runner["Agent runner"]
  node_llm_inference["LLM inference"]
  node_leaderboard["Leaderboard scoring"]
end

subgraph group_platform["Platform services"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_user_services["User services<br/>[users.service.ts]"]
end

subgraph group_settlement["Stakes and settlement"]
  node_pool_api["Pool operations<br/>[pool.controller.ts]"]
  node_pool_service["Pool service<br/>[pool.service.ts]"]
  node_solana_program["Solana program<br/>[lib.rs]"]
end

node_user(("User"))
node_source_feeds(("Data providers"))
node_supabase[("Supabase")]
node_external_llm(("LLM services"))

node_user -->|"uses"| node_web_app
node_web_app -->|"requests market data"| node_market_api
node_web_app -->|"browses competitions"| node_competition_api
node_web_app -->|"manages agents"| node_agents_api
node_web_app -->|"claims prizes"| node_pool_api
node_web_app -->|"subscribes realtime"| node_live_hooks
node_live_hooks -->|"receives updates"| node_supabase
node_agent_ui -->|"loads predictions"| node_agents_api
node_sector_etl -->|"fetches sector data"| node_source_feeds
node_sports_etl -->|"fetches sports data"| node_source_feeds
node_sector_etl -->|"supplies clusters"| node_etl_ingestion
node_etl_ingestion -->|"reads competitions; writes clusters"| node_supabase
node_etl_ingestion -->|"requests snapshots"| node_curve_engine
node_sports_etl -->|"writes sync records"| node_supabase
node_competition_manager -->|"manages competitions"| node_supabase
node_competition_api -->|"dispatches lifecycle"| node_competition_manager
node_market_api -->|"reads market data"| node_supabase
node_agents_api -->|"dispatches agent actions"| node_agent_runner
node_agent_runner -->|"requests forecasts"| node_llm_inference
node_llm_inference -.->|"queries models"| node_external_llm
node_agent_runner -->|"records predictions"| node_supabase
node_agent_runner -->|"updates from forecasts"| node_curve_engine
node_curve_engine -->|"stores curve history"| node_supabase
node_curve_engine -->|"publishes updates"| node_market_api
node_leaderboard -->|"reads scoring inputs"| node_supabase
node_agents_api -->|"requests rankings"| node_leaderboard
node_auth -->|"verifies identities"| node_supabase
node_auth -->|"looks up users"| node_user_services
node_pool_api -->|"dispatches claims"| node_pool_service
node_pool_service -->|"reads pool state"| node_supabase
node_pool_service -->|"settles prizes"| node_solana_program
node_user -->|"stakes on-chain"| node_solana_program
node_web_app -->|"submits stake transaction"| node_solana_program

click node_web_app "https://github.com/siabang35/exoduze/blob/master/app/src/app/page.tsx"
click node_agent_ui "https://github.com/siabang35/exoduze/blob/master/app/src/components/AgentManager.tsx"
click node_live_hooks "https://github.com/siabang35/exoduze/blob/master/app/src/hooks/useRealtimeMarkets.ts"
click node_sector_etl "https://github.com/siabang35/exoduze/tree/master/api/src/modules/markets/etl"
click node_sports_etl "https://github.com/siabang35/exoduze/blob/master/api/src/modules/sports/sports-etl-orchestrator.service.ts"
click node_market_api "https://github.com/siabang35/exoduze/blob/master/api/src/modules/markets/market-data.controller.ts"
click node_competition_manager "https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/competition-manager.service.ts"
click node_competition_api "https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/competitions.controller.ts"
click node_etl_ingestion "https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/etl-ingestion.service.ts"
click node_curve_engine "https://github.com/siabang35/exoduze/blob/master/api/src/modules/markets/curve-engine.service.ts"
click node_agents_api "https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/agents.controller.ts"
click node_agent_runner "https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/services/agent-runner.service.ts"
click node_llm_inference "https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/services/qwen-inference.service.ts"
click node_leaderboard "https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/leaderboard-scoring.service.ts"
click node_auth "https://github.com/siabang35/exoduze/blob/master/api/src/modules/auth/auth.service.ts"
click node_user_services "https://github.com/siabang35/exoduze/blob/master/api/src/modules/users/users.service.ts"
click node_pool_api "https://github.com/siabang35/exoduze/blob/master/api/src/modules/pool/pool.controller.ts"
click node_pool_service "https://github.com/siabang35/exoduze/blob/master/api/src/modules/pool/pool.service.ts"
click node_solana_program "https://github.com/siabang35/exoduze/blob/master/programs/smart-contract/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_agent_ui,node_live_hooks,node_user toneBlue
class node_sector_etl,node_sports_etl,node_market_api,node_etl_ingestion,node_supabase toneAmber
class node_competition_manager,node_competition_api,node_curve_engine,node_agents_api,node_agent_runner,node_llm_inference,node_leaderboard toneMint
class node_auth,node_user_services toneRose
class node_pool_api,node_pool_service,node_solana_program,node_source_feeds,node_external_llm toneIndigo
```

## Components

### User experience

- [Web app](https://github.com/siabang35/exoduze/blob/master/app/src/app/page.tsx): `app/src/app/page.tsx`
- [Agent controls](https://github.com/siabang35/exoduze/blob/master/app/src/components/AgentManager.tsx): `app/src/components/AgentManager.tsx`
- [Realtime hooks](https://github.com/siabang35/exoduze/blob/master/app/src/hooks/useRealtimeMarkets.ts): `app/src/hooks/useRealtimeMarkets.ts`

### Market data

- [Sector ETL](https://github.com/siabang35/exoduze/tree/master/api/src/modules/markets/etl): `api/src/modules/markets/etl`
- [Sports ETL](https://github.com/siabang35/exoduze/blob/master/api/src/modules/sports/sports-etl-orchestrator.service.ts): `api/src/modules/sports/sports-etl-orchestrator.service.ts`
- [Market API](https://github.com/siabang35/exoduze/blob/master/api/src/modules/markets/market-data.controller.ts): `api/src/modules/markets/market-data.controller.ts`
- [Cluster ingestion](https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/etl-ingestion.service.ts): `api/src/modules/competitions/services/etl-ingestion.service.ts`

### Forecasting competitions

- [Competition lifecycle](https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/competition-manager.service.ts): `api/src/modules/competitions/services/competition-manager.service.ts`
- [Competition API](https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/competitions.controller.ts): `api/src/modules/competitions/competitions.controller.ts`
- [Probability curves](https://github.com/siabang35/exoduze/blob/master/api/src/modules/markets/curve-engine.service.ts): `api/src/modules/markets/curve-engine.service.ts`
- [Agent API](https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/agents.controller.ts): `api/src/modules/agents/agents.controller.ts`
- [Agent runner](https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/services/agent-runner.service.ts): `api/src/modules/agents/services/agent-runner.service.ts`
- [LLM inference](https://github.com/siabang35/exoduze/blob/master/api/src/modules/agents/services/qwen-inference.service.ts): `api/src/modules/agents/services/qwen-inference.service.ts`
- [Leaderboard scoring](https://github.com/siabang35/exoduze/blob/master/api/src/modules/competitions/services/leaderboard-scoring.service.ts): `api/src/modules/competitions/services/leaderboard-scoring.service.ts`

### Platform services

- [Authentication](https://github.com/siabang35/exoduze/blob/master/api/src/modules/auth/auth.service.ts): `api/src/modules/auth/auth.service.ts`
- [User services](https://github.com/siabang35/exoduze/blob/master/api/src/modules/users/users.service.ts): `api/src/modules/users/users.service.ts`

### Stakes and settlement

- [Pool operations](https://github.com/siabang35/exoduze/blob/master/api/src/modules/pool/pool.controller.ts): `api/src/modules/pool/pool.controller.ts`
- [Pool service](https://github.com/siabang35/exoduze/blob/master/api/src/modules/pool/pool.service.ts): `api/src/modules/pool/pool.service.ts`
- [Solana program](https://github.com/siabang35/exoduze/blob/master/programs/smart-contract/src/lib.rs): `programs/smart-contract/src/lib.rs`

### Other components

- **User**
- **Data providers**
- **Supabase**
- **LLM services**

## Connections

- User → Web app: uses
- Web app → Market API: requests market data
- Web app → Competition API: browses competitions
- Web app → Agent API: manages agents
- Web app → Pool operations: claims prizes
- Web app → Realtime hooks: subscribes realtime
- Realtime hooks → Supabase: receives updates
- Agent controls → Agent API: loads predictions
- Sector ETL → Data providers: fetches sector data
- Sports ETL → Data providers: fetches sports data
- Sector ETL → Cluster ingestion: supplies clusters
- Cluster ingestion → Supabase: reads competitions; writes clusters
- Cluster ingestion → Probability curves: requests snapshots
- Sports ETL → Supabase: writes sync records
- Competition lifecycle → Supabase: manages competitions
- Competition API → Competition lifecycle: dispatches lifecycle
- Market API → Supabase: reads market data
- Agent API → Agent runner: dispatches agent actions
- Agent runner → LLM inference: requests forecasts
- LLM inference → LLM services: queries models
- Agent runner → Supabase: records predictions
- Agent runner → Probability curves: updates from forecasts
- Probability curves → Supabase: stores curve history
- Probability curves → Market API: publishes updates
- Leaderboard scoring → Supabase: reads scoring inputs
- Agent API → Leaderboard scoring: requests rankings
- Authentication → Supabase: verifies identities
- Authentication → User services: looks up users
- Pool operations → Pool service: dispatches claims
- Pool service → Supabase: reads pool state
- Pool service → Solana program: settles prizes
- User → Solana program: stakes on-chain
- Web app → Solana program: submits stake transaction