# sahilsatyam/astraeus architecture

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

- Interactive diagram: https://gitdiagram.com/sahilsatyam/astraeus
- Repository: https://github.com/sahilsatyam/astraeus

## Overview

Astraeus is a quantitative trading and research platform. Operators and researchers use the web terminal to inspect market and portfolio data, run research and recommendations, review approvals, and operate orders and safety controls. Market and alternative data are ingested and processed into features; recommendation, portfolio, and backtest capabilities support analysis before execution through the OMS. The README documents additional RAG/copilot and reconciliation flows. Arrows follow sampled orchestration and API code where available, with documented capabilities filling key branches; unsampled wiring is not inferred.

Main entry points: [`apps/api/astraeus_api/app.py`](https://github.com/sahilsatyam/astraeus/blob/main/apps/api/astraeus_api/app.py) (Research API), [`apps/recon_worker/astraeus_recon_worker/worker.py`](https://github.com/sahilsatyam/astraeus/blob/main/apps/recon_worker/astraeus_recon_worker/worker.py) (Reconciliation worker), [`apps/oms/astraeus_oms/routes.py`](https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/routes.py) (OMS routes), [`libs/marketdata/astraeus_marketdata/ingestion.py`](https://github.com/sahilsatyam/astraeus/blob/main/libs/marketdata/astraeus_marketdata/ingestion.py) (Market data ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Operator terminal"]
  node_webui["Web terminal<br/>[page.tsx]"]
  node_proxy["Authenticated API proxy<br/>[route.ts]"]
end

subgraph group_data["Data ingestion"]
  node_marketworker["Market data workers<br/>[main.py]"]
  node_ingestion["Market data ingestion<br/>[ingestion.py]"]
  node_marketadapters["Market data adapters<br/>[base.py]"]
  node_altpipeline["Alternative data NLP<br/>[pipeline.py]"]
end

subgraph group_research["Research and analytics"]
  node_features["Feature store<br/>[registry.py]"]
  node_recommender["Recommendation pipeline<br/>[orchestrator.py]"]
  node_ensemble["Signal ensemble<br/>[engine.py]"]
  node_portfolio["Portfolio optimization<br/>[__init__.py]"]
  node_strategy["Backtesting<br/>[event_driven.py]"]
  node_rag["Hybrid retrieval<br/>[retriever.py]"]
  node_agents["AI agent runtime<br/>[orchestrator.py]"]
end

subgraph group_trading["Trading operations"]
  node_omsroutes["OMS routes<br/>[routes.py]"]
  node_omsservice["OMS service<br/>[service.py]"]
  node_killswitch["Kill switch"]
  node_recon["Reconciliation worker<br/>[worker.py]"]
end

subgraph group_platform["Platform services"]
  node_api["Research API<br/>[app.py]"]
  node_postgres[("PostgreSQL / pgvector")]
  node_redis["Redis streams"]
end

node_operator(("Operator / researcher"))
node_broker["Broker APIs"]
node_llm["LLM providers"]
node_altproviders["Alternative data sources"]

node_operator -->|"uses"| node_webui
node_webui -->|"requests"| node_proxy
node_proxy -->|"forwards requests"| node_api
node_operator -->|"submits orders"| node_omsroutes
node_omsroutes -->|"delegates"| node_omsservice
node_omsservice -->|"routes orders"| node_broker
node_omsroutes -->|"reads / writes"| node_postgres
node_operator -->|"arms controls"| node_killswitch
node_killswitch -->|"stores state and journal"| node_postgres
node_recon -->|"fetches positions"| node_broker
node_recon -->|"reads local positions"| node_postgres
node_recon -->|"reports differences"| node_omsroutes
node_recon -->|"publishes alerts"| node_redis
node_marketworker -->|"runs ingestion"| node_ingestion
node_marketworker -->|"relays outbox"| node_redis
node_ingestion -->|"fetches bars"| node_marketadapters
node_ingestion -->|"writes bars and lineage"| node_postgres
node_altproviders -.->|"supplies documents"| node_altpipeline
node_altpipeline -->|"persists processed data"| node_postgres
node_api -->|"serves feature routes"| node_features
node_api -->|"serves recommendations"| node_recommender
node_recommender -->|"combines signals"| node_ensemble
node_recommender -->|"optimizes portfolio"| node_portfolio
node_features -->|"supports backtests"| node_strategy
node_api -->|"serves retrieval routes"| node_rag
node_api -->|"serves agent routes"| node_agents
node_agents -->|"retrieves context"| node_rag
node_agents -.->|"requests completions"| node_llm

click node_webui "https://github.com/sahilsatyam/astraeus/blob/main/apps/web/src/app/page.tsx"
click node_proxy "https://github.com/sahilsatyam/astraeus/blob/main/apps/web/src/app/api/proxy/%5B...path%5D/route.ts"
click node_api "https://github.com/sahilsatyam/astraeus/blob/main/apps/api/astraeus_api/app.py"
click node_omsroutes "https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/routes.py"
click node_omsservice "https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/service.py"
click node_killswitch "https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/kill_switch_routes.py"
click node_recon "https://github.com/sahilsatyam/astraeus/blob/main/apps/recon_worker/astraeus_recon_worker/worker.py"
click node_marketworker "https://github.com/sahilsatyam/astraeus/blob/main/apps/workers/astraeus_workers/main.py"
click node_ingestion "https://github.com/sahilsatyam/astraeus/blob/main/libs/marketdata/astraeus_marketdata/ingestion.py"
click node_marketadapters "https://github.com/sahilsatyam/astraeus/blob/main/libs/marketdata/astraeus_marketdata/adapters/base.py"
click node_altpipeline "https://github.com/sahilsatyam/astraeus/blob/main/libs/altdata/astraeus_altdata/pipeline.py"
click node_features "https://github.com/sahilsatyam/astraeus/blob/main/libs/features/astraeus_features/registry.py"
click node_recommender "https://github.com/sahilsatyam/astraeus/blob/main/libs/recommender/astraeus_recommender/orchestrator.py"
click node_ensemble "https://github.com/sahilsatyam/astraeus/blob/main/libs/ensemble/astraeus_ensemble/engine.py"
click node_portfolio "https://github.com/sahilsatyam/astraeus/blob/main/libs/portfolio/astraeus_portfolio/optimizers/__init__.py"
click node_strategy "https://github.com/sahilsatyam/astraeus/blob/main/libs/strategy/astraeus_strategy/engines/event_driven.py"
click node_rag "https://github.com/sahilsatyam/astraeus/blob/main/libs/rag/astraeus_rag/retriever.py"
click node_agents "https://github.com/sahilsatyam/astraeus/blob/main/libs/agent_runtime/astraeus_agent_runtime/orchestrator.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_webui,node_proxy toneBlue
class node_marketworker,node_ingestion,node_marketadapters,node_altpipeline toneAmber
class node_features,node_recommender,node_ensemble,node_portfolio,node_strategy,node_rag,node_agents,node_broker toneMint
class node_omsroutes,node_omsservice,node_killswitch,node_recon toneRose
class node_api,node_postgres,node_redis,node_operator,node_llm,node_altproviders toneIndigo
```

## Components

### Operator terminal

- [Web terminal](https://github.com/sahilsatyam/astraeus/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Authenticated API proxy](https://github.com/sahilsatyam/astraeus/blob/main/apps/web/src/app/api/proxy/%5B...path%5D/route.ts): `apps/web/src/app/api/proxy/[...path]/route.ts`

### Data ingestion

- [Market data workers](https://github.com/sahilsatyam/astraeus/blob/main/apps/workers/astraeus_workers/main.py): `apps/workers/astraeus_workers/main.py`
- [Market data ingestion](https://github.com/sahilsatyam/astraeus/blob/main/libs/marketdata/astraeus_marketdata/ingestion.py): `libs/marketdata/astraeus_marketdata/ingestion.py`
- [Market data adapters](https://github.com/sahilsatyam/astraeus/blob/main/libs/marketdata/astraeus_marketdata/adapters/base.py): `libs/marketdata/astraeus_marketdata/adapters/base.py`
- [Alternative data NLP](https://github.com/sahilsatyam/astraeus/blob/main/libs/altdata/astraeus_altdata/pipeline.py): `libs/altdata/astraeus_altdata/pipeline.py`

### Research and analytics

- [Feature store](https://github.com/sahilsatyam/astraeus/blob/main/libs/features/astraeus_features/registry.py): `libs/features/astraeus_features/registry.py`
- [Recommendation pipeline](https://github.com/sahilsatyam/astraeus/blob/main/libs/recommender/astraeus_recommender/orchestrator.py): `libs/recommender/astraeus_recommender/orchestrator.py`
- [Signal ensemble](https://github.com/sahilsatyam/astraeus/blob/main/libs/ensemble/astraeus_ensemble/engine.py): `libs/ensemble/astraeus_ensemble/engine.py`
- [Portfolio optimization](https://github.com/sahilsatyam/astraeus/blob/main/libs/portfolio/astraeus_portfolio/optimizers/__init__.py): `libs/portfolio/astraeus_portfolio/optimizers/__init__.py`
- [Backtesting](https://github.com/sahilsatyam/astraeus/blob/main/libs/strategy/astraeus_strategy/engines/event_driven.py): `libs/strategy/astraeus_strategy/engines/event_driven.py`
- [Hybrid retrieval](https://github.com/sahilsatyam/astraeus/blob/main/libs/rag/astraeus_rag/retriever.py): `libs/rag/astraeus_rag/retriever.py`
- [AI agent runtime](https://github.com/sahilsatyam/astraeus/blob/main/libs/agent_runtime/astraeus_agent_runtime/orchestrator.py): `libs/agent_runtime/astraeus_agent_runtime/orchestrator.py`

### Trading operations

- [OMS routes](https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/routes.py): `apps/oms/astraeus_oms/routes.py`
- [OMS service](https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/service.py): `apps/oms/astraeus_oms/service.py`
- [Kill switch](https://github.com/sahilsatyam/astraeus/blob/main/apps/oms/astraeus_oms/kill_switch_routes.py): `apps/oms/astraeus_oms/kill_switch_routes.py`
- [Reconciliation worker](https://github.com/sahilsatyam/astraeus/blob/main/apps/recon_worker/astraeus_recon_worker/worker.py): `apps/recon_worker/astraeus_recon_worker/worker.py`

### Platform services

- [Research API](https://github.com/sahilsatyam/astraeus/blob/main/apps/api/astraeus_api/app.py): `apps/api/astraeus_api/app.py`
- **PostgreSQL / pgvector**
- **Redis streams**

### Other components

- **Operator / researcher**
- **Broker APIs**
- **LLM providers**
- **Alternative data sources**

## Connections

- Operator / researcher → Web terminal: uses
- Web terminal → Authenticated API proxy: requests
- Authenticated API proxy → Research API: forwards requests
- Operator / researcher → OMS routes: submits orders
- OMS routes → OMS service: delegates
- OMS service → Broker APIs: routes orders
- OMS routes → PostgreSQL / pgvector: reads / writes
- Operator / researcher → Kill switch: arms controls
- Kill switch → PostgreSQL / pgvector: stores state and journal
- Reconciliation worker → Broker APIs: fetches positions
- Reconciliation worker → PostgreSQL / pgvector: reads local positions
- Reconciliation worker → OMS routes: reports differences
- Reconciliation worker → Redis streams: publishes alerts
- Market data workers → Market data ingestion: runs ingestion
- Market data workers → Redis streams: relays outbox
- Market data ingestion → Market data adapters: fetches bars
- Market data ingestion → PostgreSQL / pgvector: writes bars and lineage
- Alternative data sources → Alternative data NLP: supplies documents
- Alternative data NLP → PostgreSQL / pgvector: persists processed data
- Research API → Feature store: serves feature routes
- Research API → Recommendation pipeline: serves recommendations
- Recommendation pipeline → Signal ensemble: combines signals
- Recommendation pipeline → Portfolio optimization: optimizes portfolio
- Feature store → Backtesting: supports backtests
- Research API → Hybrid retrieval: serves retrieval routes
- Research API → AI agent runtime: serves agent routes
- AI agent runtime → Hybrid retrieval: retrieves context
- AI agent runtime → LLM providers: requests completions