# dayyansheikh/arepo architecture

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

- Interactive diagram: https://gitdiagram.com/dayyansheikh/arepo
- Repository: https://github.com/dayyansheikh/arepo

## Overview

Arepo is a read-only prediction-market research and screening product. Users explore markets, inspect explainable anomaly signals and opportunity rankings, and review replay or prospective-cohort results through a frontend backed by FastAPI. The backend normalizes public Polymarket data, serves live/cached/replay modes, and supports accounts and alerts. The map preserves the documented research, evaluation, and education surfaces; several unsampled routes and services are represented by their existing directories, and their internal links are omitted where source evidence was unavailable.

Main entry points: [`backend/astrolabe/service/market_service.py`](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/service/market_service.py) (Market service), [`backend/astrolabe/ingest/pipeline.py`](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/ingest/pipeline.py) (Ingestion pipeline), [`frontend/lib/api.ts`](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/frontend/lib/api.ts) (API client), [`backend/astrolabe/evaluation/research_engine.py`](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/research_engine.py) (Cohort selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Research frontend"]
  node_web["Arepo surfaces"]
  node_webapi["API client<br/>[api.ts]"]
  node_accountui["Account pages<br/>[page.tsx]"]
end

subgraph group_api["API and market services"]
  node_apiapp["FastAPI app<br/>[app.py]"]
  node_routes["Product routes"]
  node_marketservice["Market service<br/>[market_service.py]"]
end

subgraph group_data["Market data and analytics"]
  node_ingest["Ingestion pipeline<br/>[pipeline.py]"]
  node_normalize["Data normalization<br/>[normalize.py]"]
  node_domain["Market domain<br/>[models.py]"]
  node_storage[("Market storage<br/>[repository.py]")]
end

subgraph group_research["Signals and evaluation"]
  node_opportunity["Opportunity board<br/>[service.py]"]
  node_analytics["Signal analytics"]
  node_replay["Replay backtest<br/>[player.py]"]
  node_discovery["Signal discovery<br/>[signal_service.py]"]
  node_cohort["Cohort selection<br/>[research_engine.py]"]
  node_weekly["Weekly evaluation<br/>[engine.py]"]
  node_evalstore[("Evaluation records")]
end

subgraph group_accounts["Accounts and alerts"]
  node_accounts["Account services"]
  node_accountmodels[("Account records<br/>[models.py]")]
  node_email["Email delivery<br/>[email.py]"]
  node_digest["Personalized digest<br/>[service.py]"]
  node_alerts["Alert providers<br/>[provider.py]"]
end

node_researcher(("Researcher"))
node_polymarket["Polymarket APIs"]

node_researcher -->|"uses"| node_web
node_web -.->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_apiapp
node_apiapp -->|"mounts"| node_routes
node_routes -.->|"serves market data"| node_marketservice
node_marketservice -->|"computes signals"| node_analytics
node_marketservice -->|"loads replay"| node_replay
node_marketservice -.->|"retrieves live data"| node_polymarket
node_ingest -->|"fetches public data"| node_polymarket
node_ingest -->|"normalizes"| node_normalize
node_normalize -->|"creates models"| node_domain
node_ingest -->|"persists snapshots"| node_storage
node_marketservice -->|"reads scan data"| node_discovery
node_discovery -->|"reads snapshots"| node_storage
node_cohort -->|"scores markets"| node_opportunity
node_cohort -->|"freezes entries"| node_evalstore
node_weekly -->|"records rankings"| node_evalstore
node_accountui -.->|"uses API"| node_webapi
node_accounts -->|"persists users"| node_accountmodels
node_accounts -->|"sends verification"| node_email
node_digest -->|"reads preferences"| node_accountmodels
node_digest -.->|"delivers alerts"| node_alerts

click node_web "https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/frontend/app"
click node_webapi "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/frontend/lib/api.ts"
click node_apiapp "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/api/app.py"
click node_routes "https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/api/routes"
click node_marketservice "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/service/market_service.py"
click node_opportunity "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/opportunity/service.py"
click node_ingest "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/ingest/pipeline.py"
click node_normalize "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/ingest/normalize.py"
click node_domain "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/domain/models.py"
click node_storage "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/storage/repository.py"
click node_analytics "https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/analytics"
click node_replay "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/replay/player.py"
click node_discovery "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/discovery/signal_service.py"
click node_cohort "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/research_engine.py"
click node_weekly "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/engine.py"
click node_evalstore "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/research_repository.py"
click node_accountui "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/frontend/app/account/page.tsx"
click node_accounts "https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/accounts"
click node_accountmodels "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/accounts/models.py"
click node_email "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/accounts/email.py"
click node_digest "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/digest/service.py"
click node_alerts "https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/alerts/provider.py"

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,node_webapi,node_accountui toneBlue
class node_apiapp,node_routes,node_marketservice toneAmber
class node_ingest,node_normalize,node_domain,node_storage,node_polymarket toneMint
class node_opportunity,node_analytics,node_replay,node_discovery,node_cohort,node_weekly,node_evalstore toneRose
class node_accounts,node_accountmodels,node_email,node_digest,node_alerts,node_researcher toneIndigo
```

## Components

### Research frontend

- [Arepo surfaces](https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/frontend/app): `frontend/app`
- [API client](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Account pages](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/frontend/app/account/page.tsx): `frontend/app/account/page.tsx`

### API and market services

- [FastAPI app](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/api/app.py): `backend/astrolabe/api/app.py`
- [Product routes](https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/api/routes): `backend/astrolabe/api/routes`
- [Market service](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/service/market_service.py): `backend/astrolabe/service/market_service.py`

### Market data and analytics

- [Ingestion pipeline](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/ingest/pipeline.py): `backend/astrolabe/ingest/pipeline.py`
- [Data normalization](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/ingest/normalize.py): `backend/astrolabe/ingest/normalize.py`
- [Market domain](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/domain/models.py): `backend/astrolabe/domain/models.py`
- [Market storage](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/storage/repository.py): `backend/astrolabe/storage/repository.py`

### Signals and evaluation

- [Opportunity board](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/opportunity/service.py): `backend/astrolabe/opportunity/service.py`
- [Signal analytics](https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/analytics): `backend/astrolabe/analytics`
- [Replay backtest](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/replay/player.py): `backend/astrolabe/replay/player.py`
- [Signal discovery](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/discovery/signal_service.py): `backend/astrolabe/discovery/signal_service.py`
- [Cohort selection](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/research_engine.py): `backend/astrolabe/evaluation/research_engine.py`
- [Weekly evaluation](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/engine.py): `backend/astrolabe/evaluation/engine.py`
- [Evaluation records](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/evaluation/research_repository.py): `backend/astrolabe/evaluation/research_repository.py`

### Accounts and alerts

- [Account services](https://github.com/dayyansheikh/arepo/tree/arepo-free-production-v1/backend/astrolabe/accounts): `backend/astrolabe/accounts`
- [Account records](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/accounts/models.py): `backend/astrolabe/accounts/models.py`
- [Email delivery](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/accounts/email.py): `backend/astrolabe/accounts/email.py`
- [Personalized digest](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/digest/service.py): `backend/astrolabe/digest/service.py`
- [Alert providers](https://github.com/dayyansheikh/arepo/blob/arepo-free-production-v1/backend/astrolabe/alerts/provider.py): `backend/astrolabe/alerts/provider.py`

### Other components

- **Researcher**
- **Polymarket APIs**

## Connections

- Researcher → Arepo surfaces: uses (evidence: `README.md`)
- Arepo surfaces → API client: requests data
- API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Product routes: mounts (evidence: `backend/astrolabe/api/app.py`)
- Product routes → Market service: serves market data
- Market service → Signal analytics: computes signals (evidence: `backend/astrolabe/service/market_service.py`)
- Market service → Replay backtest: loads replay (evidence: `backend/astrolabe/service/market_service.py`)
- Market service → Polymarket APIs: retrieves live data
- Ingestion pipeline → Polymarket APIs: fetches public data (evidence: `backend/astrolabe/ingest/pipeline.py`)
- Ingestion pipeline → Data normalization: normalizes (evidence: `backend/astrolabe/ingest/pipeline.py`)
- Data normalization → Market domain: creates models (evidence: `backend/astrolabe/ingest/normalize.py`)
- Ingestion pipeline → Market storage: persists snapshots (evidence: `backend/astrolabe/ingest/pipeline.py`)
- Market service → Signal discovery: reads scan data (evidence: `backend/astrolabe/service/market_service.py`)
- Signal discovery → Market storage: reads snapshots (evidence: `backend/astrolabe/discovery/signal_service.py`)
- Cohort selection → Opportunity board: scores markets (evidence: `backend/astrolabe/evaluation/research_engine.py`)
- Cohort selection → Evaluation records: freezes entries (evidence: `backend/astrolabe/evaluation/research_engine.py`)
- Weekly evaluation → Evaluation records: records rankings (evidence: `backend/astrolabe/evaluation/engine.py`)
- Account pages → API client: uses API
- Account services → Account records: persists users (evidence: `backend/astrolabe/accounts/models.py`)
- Account services → Email delivery: sends verification (evidence: `backend/astrolabe/accounts/manager.py`)
- Personalized digest → Account records: reads preferences (evidence: `backend/astrolabe/digest/service.py`)
- Personalized digest → Alert providers: delivers alerts (evidence: `backend/astrolabe/digest/service.py`)