# botv99/scheme-intel architecture

> Architecture diagram of the GitHub repository botv99/scheme-intel, 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/botv99/scheme-intel
- Repository: https://github.com/botv99/scheme-intel

## Overview

Scheme Intel monitors Indian renewable-energy and bioenergy policy and company developments, maps evidence to listed companies, evaluates swing-trade setups, tracks outcomes, and delivers Telegram intelligence. Its principal workflow runs from source ingestion and catalyst analysis through market/risk assessment, persistence, and alerting; a separate Telegram query path serves prebuilt intelligence or queues deep research. Relationships reflect the README and sampled orchestration, routing, and storage code; several subsystems are documented but their internal wiring was not sampled.

Main entry points: [`src/scheme_intel/stage2/pipeline.py`](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/pipeline.py) (Stage 2 pipeline), [`src/scheme_intel/research/worker.py`](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/worker.py) (Research worker), [`src/scheme_intel/ingest.py`](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingest.py) (Snapshot ingestion), [`src/scheme_intel/pipeline/orchestration.py`](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/pipeline/orchestration.py) (Stage 1 pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evidence["Evidence collection"]
  node_ingest["Snapshot ingestion<br/>[ingest.py]"]
  node_exchange_ingest["Exchange activity<br/>[exchanges.py]"]
  node_media_ingest["News ingestion<br/>[media.py]"]
  node_price_ingest["Price ingestion<br/>[price.py]"]
end

subgraph group_analysis["Catalyst and market analysis"]
  node_main["Unified entry point<br/>[main.py]"]
  node_stage1["Stage 1 pipeline<br/>[orchestration.py]"]
  node_stage1_steps["Stage 1 analysis<br/>[stage1.py]"]
  node_intelligence["Catalyst intelligence"]
end

subgraph group_trading["Trade decisions and tracking"]
  node_stage2["Stage 2 pipeline<br/>[pipeline.py]"]
  node_market_engine["Market snapshots<br/>[market.py]"]
  node_candidate["Setup candidates<br/>[candidate.py]"]
  node_debate["Agent debate<br/>[debate.py]"]
  node_provider_manager["LLM failover<br/>[manager.py]"]
  node_risk["Risk and waiting<br/>[risk.py]"]
  node_outcomes["Outcome tracking<br/>[tracker.py]"]
  node_delivery["Alert delivery<br/>[service.py]"]
end

subgraph group_conversation["Telegram intelligence"]
  node_snapshot["Snapshot retrieval<br/>[retrieval.py]"]
  node_memory_store["Snapshot store<br/>[store.py]"]
  node_router["Message router<br/>[telegram_router.py]"]
  node_research_queue["Research queue<br/>[queue.py]"]
  node_research_worker["Research worker<br/>[worker.py]"]
  node_research_executor["Research executor<br/>[executor.py]"]
end

subgraph group_persistence["Persistence and analytics"]
  node_database[("SQLite history<br/>[storage.py]")]
  node_performance["Performance analytics<br/>[performance.py]"]
end

node_operator(("Monitor operator"))
node_official(("Official sources"))
node_company_feeds(("Company and media feeds"))
node_market_feeds(("Market data feeds"))
node_telegram_user(("Telegram user"))
node_telegram(("Telegram service"))

node_operator -->|"runs scan"| node_main
node_operator -->|"refreshes data"| node_ingest
node_official -->|"provides disclosures"| node_exchange_ingest
node_company_feeds -->|"provides news"| node_media_ingest
node_market_feeds -->|"provides prices"| node_price_ingest
node_ingest -->|"collects activity"| node_exchange_ingest
node_ingest -->|"collects news"| node_media_ingest
node_ingest -->|"collects prices"| node_price_ingest
node_main -->|"runs Stage 1"| node_stage1
node_main -->|"runs Stage 2"| node_stage2
node_stage1 -->|"orchestrates analysis"| node_stage1_steps
node_stage1_steps -->|"evaluates catalysts"| node_intelligence
node_exchange_ingest -.->|"supplies activity"| node_stage1
node_media_ingest -.->|"supplies news"| node_stage1
node_price_ingest -.->|"supplies snapshots"| node_stage2
node_stage2 -->|"builds market data"| node_market_engine
node_stage2 -->|"finds setups"| node_candidate
node_stage2 -->|"requests debate"| node_debate
node_debate -->|"generates analysis"| node_provider_manager
node_stage2 -->|"applies risk checks"| node_risk
node_stage2 -->|"persists setups"| node_database
node_outcomes -->|"stores outcomes"| node_database
node_performance -->|"reads history"| node_database
node_stage2 -->|"updates outcomes"| node_outcomes
node_stage2 -->|"summarizes performance"| node_performance
node_stage2 -->|"dispatches report"| node_delivery
node_delivery -->|"sends alerts"| node_telegram
node_telegram_user -->|"sends query"| node_router
node_router -->|"queries memory"| node_snapshot
node_snapshot -->|"loads snapshot"| node_memory_store
node_router -->|"enqueues research"| node_research_queue
node_research_worker -->|"claims jobs"| node_research_queue
node_research_worker -->|"executes job"| node_research_executor
node_research_worker -->|"saves result"| node_research_queue
node_research_worker -->|"sends findings"| node_telegram

click node_main "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/main.py"
click node_ingest "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingest.py"
click node_exchange_ingest "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/exchanges.py"
click node_media_ingest "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/media.py"
click node_price_ingest "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/price.py"
click node_stage1 "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/pipeline/orchestration.py"
click node_stage1_steps "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/pipeline/stage1.py"
click node_intelligence "https://github.com/botv99/scheme-intel/tree/main/src/scheme_intel/intelligence"
click node_stage2 "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/pipeline.py"
click node_market_engine "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/market.py"
click node_candidate "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/candidate.py"
click node_debate "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/debate.py"
click node_provider_manager "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/providers/manager.py"
click node_risk "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/risk.py"
click node_outcomes "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/tracker.py"
click node_database "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/storage.py"
click node_performance "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/performance.py"
click node_delivery "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/delivery/service.py"
click node_snapshot "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/intelligence_memory/retrieval.py"
click node_memory_store "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/intelligence_memory/store.py"
click node_router "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/delivery/telegram_router.py"
click node_research_queue "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/queue.py"
click node_research_worker "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/worker.py"
click node_research_executor "https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/executor.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_ingest,node_exchange_ingest,node_media_ingest,node_price_ingest,node_telegram_user toneBlue
class node_main,node_stage1,node_stage1_steps,node_intelligence toneAmber
class node_stage2,node_market_engine,node_candidate,node_debate,node_provider_manager,node_risk,node_outcomes,node_delivery toneMint
class node_snapshot,node_memory_store,node_router,node_research_queue,node_research_worker,node_research_executor toneRose
class node_database,node_performance,node_operator,node_official,node_company_feeds,node_market_feeds,node_telegram toneIndigo
```

## Components

### Evidence collection

- [Snapshot ingestion](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingest.py): `src/scheme_intel/ingest.py`
- [Exchange activity](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/exchanges.py): `src/scheme_intel/ingestion/exchanges.py`
- [News ingestion](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/media.py): `src/scheme_intel/ingestion/media.py`
- [Price ingestion](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/ingestion/price.py): `src/scheme_intel/ingestion/price.py`

### Catalyst and market analysis

- [Unified entry point](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/main.py): `src/scheme_intel/main.py`
- [Stage 1 pipeline](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/pipeline/orchestration.py): `src/scheme_intel/pipeline/orchestration.py`
- [Stage 1 analysis](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/pipeline/stage1.py): `src/scheme_intel/pipeline/stage1.py`
- [Catalyst intelligence](https://github.com/botv99/scheme-intel/tree/main/src/scheme_intel/intelligence): `src/scheme_intel/intelligence`

### Trade decisions and tracking

- [Stage 2 pipeline](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/pipeline.py): `src/scheme_intel/stage2/pipeline.py`
- [Market snapshots](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/market.py): `src/scheme_intel/stage2/market.py`
- [Setup candidates](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/candidate.py): `src/scheme_intel/stage2/candidate.py`
- [Agent debate](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/debate.py): `src/scheme_intel/stage2/debate.py`
- [LLM failover](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/providers/manager.py): `src/scheme_intel/stage2/providers/manager.py`
- [Risk and waiting](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/risk.py): `src/scheme_intel/stage2/risk.py`
- [Outcome tracking](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/tracker.py): `src/scheme_intel/stage2/tracker.py`
- [Alert delivery](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/delivery/service.py): `src/scheme_intel/delivery/service.py`

### Telegram intelligence

- [Snapshot retrieval](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/intelligence_memory/retrieval.py): `src/scheme_intel/intelligence_memory/retrieval.py`
- [Snapshot store](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/intelligence_memory/store.py): `src/scheme_intel/intelligence_memory/store.py`
- [Message router](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/delivery/telegram_router.py): `src/scheme_intel/delivery/telegram_router.py`
- [Research queue](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/queue.py): `src/scheme_intel/research/queue.py`
- [Research worker](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/worker.py): `src/scheme_intel/research/worker.py`
- [Research executor](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/research/executor.py): `src/scheme_intel/research/executor.py`

### Persistence and analytics

- [SQLite history](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/storage.py): `src/scheme_intel/stage2/storage.py`
- [Performance analytics](https://github.com/botv99/scheme-intel/blob/main/src/scheme_intel/stage2/performance.py): `src/scheme_intel/stage2/performance.py`

### Other components

- **Monitor operator**
- **Official sources**
- **Company and media feeds**
- **Market data feeds**
- **Telegram user**
- **Telegram service**

## Connections

- Monitor operator → Unified entry point: runs scan
- Monitor operator → Snapshot ingestion: refreshes data
- Official sources → Exchange activity: provides disclosures
- Company and media feeds → News ingestion: provides news
- Market data feeds → Price ingestion: provides prices
- Snapshot ingestion → Exchange activity: collects activity
- Snapshot ingestion → News ingestion: collects news
- Snapshot ingestion → Price ingestion: collects prices
- Unified entry point → Stage 1 pipeline: runs Stage 1
- Unified entry point → Stage 2 pipeline: runs Stage 2
- Stage 1 pipeline → Stage 1 analysis: orchestrates analysis
- Stage 1 analysis → Catalyst intelligence: evaluates catalysts
- Exchange activity → Stage 1 pipeline: supplies activity
- News ingestion → Stage 1 pipeline: supplies news
- Price ingestion → Stage 2 pipeline: supplies snapshots
- Stage 2 pipeline → Market snapshots: builds market data
- Stage 2 pipeline → Setup candidates: finds setups
- Stage 2 pipeline → Agent debate: requests debate
- Agent debate → LLM failover: generates analysis
- Stage 2 pipeline → Risk and waiting: applies risk checks
- Stage 2 pipeline → SQLite history: persists setups
- Outcome tracking → SQLite history: stores outcomes
- Performance analytics → SQLite history: reads history
- Stage 2 pipeline → Outcome tracking: updates outcomes
- Stage 2 pipeline → Performance analytics: summarizes performance
- Stage 2 pipeline → Alert delivery: dispatches report
- Alert delivery → Telegram service: sends alerts
- Telegram user → Message router: sends query
- Message router → Snapshot retrieval: queries memory
- Snapshot retrieval → Snapshot store: loads snapshot
- Message router → Research queue: enqueues research
- Research worker → Research queue: claims jobs
- Research worker → Research executor: executes job
- Research worker → Research queue: saves result
- Research worker → Telegram service: sends findings