# voxtech-byte/invest architecture

> Architecture diagram of the GitHub repository voxtech-byte/invest, 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/voxtech-byte/invest
- Repository: https://github.com/voxtech-byte/invest

## Overview

Sovereign is an IDX quantitative trading terminal with an interactive Streamlit dashboard and a separate automated scanning/execution entry point. The principal workflow fetches market data, enriches it with quantitative and institutional signals, applies portfolio and exit-risk checks, then presents results or executes trades and records/alerts them. The README documents additional risk and intelligence capabilities included here, though several are represented only by their repository paths; sampled excerpts do not establish all internal call wiring.

Main entry points: [`main.py`](https://github.com/voxtech-byte/invest/blob/main/main.py) (Automated Runner), [`core/signals.py`](https://github.com/voxtech-byte/invest/blob/main/core/signals.py) (Signal Scoring), [`app.py`](https://github.com/voxtech-byte/invest/blob/main/app.py) (Streamlit Dashboard), [`data/database.py`](https://github.com/voxtech-byte/invest/blob/main/data/database.py) (Portfolio Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_dashboard_app["Streamlit Dashboard<br/>[app.py]"]
  node_auto_runner["Automated Runner<br/>[main.py]"]
end

subgraph group_market["Market Intelligence"]
  node_fetcher["Market Data Fetcher<br/>[data_fetcher.py]"]
  node_market_sources{{"Market Data APIs"}}
  node_news["News Intelligence<br/>[news_aggregator.py]"]
  node_indicators["Technical Indicators<br/>[indicators.py]"]
end

subgraph group_trading["Trading and Risk"]
  node_signals["Signal Scoring<br/>[signals.py]"]
  node_institutional["Institutional Analysis<br/>[institutional.py]"]
  node_monte_carlo["Monte Carlo Risk<br/>[monte_carlo.py]"]
  node_dark_pool["Dark Pool Detection<br/>[dark_pool.py]"]
  node_black_swan["Black Swan Alarm<br/>[black_swan.py]"]
  node_sector_rotation["Sector Rotation<br/>[sector_rotation.py]"]
  node_executive["Execution Risk Gates<br/>[executive.py]"]
end

subgraph group_state["Portfolio and Integrations"]
  node_broker["Broker Simulator<br/>[mock_broker.py]"]
  node_database[("Portfolio Records<br/>[database.py]")]
  node_local_files[("Local JSON Mirrors")]
  node_supabase[("Supabase")]
  node_sheets["Google Sheets Logger"]
  node_telegram["Telegram Alerts<br/>[alerts.py]"]
  node_telegram_queue["Telegram Queue<br/>[telegram_queue.py]"]
end

subgraph group_dashboard["Dashboard Experience"]
  node_dashboard_ui["Dashboard Components"]
  node_terminal_ui["Terminal Styling<br/>[terminal_style.py]"]
end

node_trader(("Trader"))
node_scheduler(("Automation Trigger"))

node_trader -->|"opens dashboard"| node_dashboard_app
node_scheduler -->|"starts scans"| node_auto_runner
node_auto_runner -->|"fetches prices"| node_fetcher
node_fetcher -->|"requests data"| node_market_sources
node_auto_runner -->|"scores symbols"| node_signals
node_signals -->|"uses indicators"| node_indicators
node_signals -->|"calculates footprint"| node_institutional
node_signals -->|"runs simulations"| node_monte_carlo
node_auto_runner -->|"checks trade gates"| node_executive
node_auto_runner -->|"executes orders"| node_broker
node_auto_runner -->|"saves positions"| node_database
node_auto_runner -->|"logs trades"| node_sheets
node_auto_runner -->|"formats alerts"| node_telegram
node_telegram -->|"queues messages"| node_telegram_queue
node_database -->|"mirrors records"| node_local_files
node_database -.->|"reads and writes"| node_supabase
node_dashboard_app -->|"renders views"| node_dashboard_ui
node_dashboard_app -->|"styles interface"| node_terminal_ui
node_dashboard_app -->|"loads market data"| node_fetcher
node_dashboard_app -->|"shows analysis"| node_signals
node_dashboard_app -->|"reads portfolio"| node_database
node_signals -.->|"uses detection"| node_dark_pool
node_signals -.->|"uses alarm"| node_black_swan
node_signals -.->|"uses sector analysis"| node_sector_rotation
node_news -->|"collects news"| node_market_sources

click node_dashboard_app "https://github.com/voxtech-byte/invest/blob/main/app.py"
click node_auto_runner "https://github.com/voxtech-byte/invest/blob/main/main.py"
click node_fetcher "https://github.com/voxtech-byte/invest/blob/main/data/data_fetcher.py"
click node_news "https://github.com/voxtech-byte/invest/blob/main/integrations/news_aggregator.py"
click node_indicators "https://github.com/voxtech-byte/invest/blob/main/core/indicators.py"
click node_signals "https://github.com/voxtech-byte/invest/blob/main/core/signals.py"
click node_institutional "https://github.com/voxtech-byte/invest/blob/main/core/institutional.py"
click node_monte_carlo "https://github.com/voxtech-byte/invest/blob/main/core/monte_carlo.py"
click node_dark_pool "https://github.com/voxtech-byte/invest/blob/main/core/dark_pool.py"
click node_black_swan "https://github.com/voxtech-byte/invest/blob/main/core/black_swan.py"
click node_sector_rotation "https://github.com/voxtech-byte/invest/blob/main/core/sector_rotation.py"
click node_executive "https://github.com/voxtech-byte/invest/blob/main/core/executive.py"
click node_broker "https://github.com/voxtech-byte/invest/blob/main/mock_broker.py"
click node_database "https://github.com/voxtech-byte/invest/blob/main/data/database.py"
click node_sheets "https://github.com/voxtech-byte/invest/blob/main/google_sheets_logger.py"
click node_telegram "https://github.com/voxtech-byte/invest/blob/main/integrations/alerts.py"
click node_telegram_queue "https://github.com/voxtech-byte/invest/blob/main/integrations/telegram_queue.py"
click node_dashboard_ui "https://github.com/voxtech-byte/invest/tree/main/components"
click node_terminal_ui "https://github.com/voxtech-byte/invest/blob/main/ui/terminal_style.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_dashboard_app,node_auto_runner toneBlue
class node_fetcher,node_market_sources,node_news,node_indicators toneAmber
class node_signals,node_institutional,node_monte_carlo,node_dark_pool,node_black_swan,node_sector_rotation,node_executive toneMint
class node_broker,node_database,node_local_files,node_supabase,node_sheets,node_telegram,node_telegram_queue toneRose
class node_dashboard_ui,node_terminal_ui,node_trader,node_scheduler toneIndigo
```

## Components

### Entry Points

- [Streamlit Dashboard](https://github.com/voxtech-byte/invest/blob/main/app.py): `app.py`
- [Automated Runner](https://github.com/voxtech-byte/invest/blob/main/main.py): `main.py`

### Market Intelligence

- [Market Data Fetcher](https://github.com/voxtech-byte/invest/blob/main/data/data_fetcher.py): `data/data_fetcher.py`
- **Market Data APIs**
- [News Intelligence](https://github.com/voxtech-byte/invest/blob/main/integrations/news_aggregator.py): `integrations/news_aggregator.py`
- [Technical Indicators](https://github.com/voxtech-byte/invest/blob/main/core/indicators.py): `core/indicators.py`

### Trading and Risk

- [Signal Scoring](https://github.com/voxtech-byte/invest/blob/main/core/signals.py): `core/signals.py`
- [Institutional Analysis](https://github.com/voxtech-byte/invest/blob/main/core/institutional.py): `core/institutional.py`
- [Monte Carlo Risk](https://github.com/voxtech-byte/invest/blob/main/core/monte_carlo.py): `core/monte_carlo.py`
- [Dark Pool Detection](https://github.com/voxtech-byte/invest/blob/main/core/dark_pool.py): `core/dark_pool.py`
- [Black Swan Alarm](https://github.com/voxtech-byte/invest/blob/main/core/black_swan.py): `core/black_swan.py`
- [Sector Rotation](https://github.com/voxtech-byte/invest/blob/main/core/sector_rotation.py): `core/sector_rotation.py`
- [Execution Risk Gates](https://github.com/voxtech-byte/invest/blob/main/core/executive.py): `core/executive.py`

### Portfolio and Integrations

- [Broker Simulator](https://github.com/voxtech-byte/invest/blob/main/mock_broker.py): `mock_broker.py`
- [Portfolio Records](https://github.com/voxtech-byte/invest/blob/main/data/database.py): `data/database.py`
- **Local JSON Mirrors**
- **Supabase**
- [Google Sheets Logger](https://github.com/voxtech-byte/invest/blob/main/google_sheets_logger.py): `google_sheets_logger.py`
- [Telegram Alerts](https://github.com/voxtech-byte/invest/blob/main/integrations/alerts.py): `integrations/alerts.py`
- [Telegram Queue](https://github.com/voxtech-byte/invest/blob/main/integrations/telegram_queue.py): `integrations/telegram_queue.py`

### Dashboard Experience

- [Dashboard Components](https://github.com/voxtech-byte/invest/tree/main/components): `components`
- [Terminal Styling](https://github.com/voxtech-byte/invest/blob/main/ui/terminal_style.py): `ui/terminal_style.py`

### Other components

- **Trader**
- **Automation Trigger**

## Connections

- Trader → Streamlit Dashboard: opens dashboard
- Automation Trigger → Automated Runner: starts scans
- Automated Runner → Market Data Fetcher: fetches prices
- Market Data Fetcher → Market Data APIs: requests data
- Automated Runner → Signal Scoring: scores symbols
- Signal Scoring → Technical Indicators: uses indicators
- Signal Scoring → Institutional Analysis: calculates footprint
- Signal Scoring → Monte Carlo Risk: runs simulations
- Automated Runner → Execution Risk Gates: checks trade gates
- Automated Runner → Broker Simulator: executes orders
- Automated Runner → Portfolio Records: saves positions
- Automated Runner → Google Sheets Logger: logs trades
- Automated Runner → Telegram Alerts: formats alerts
- Telegram Alerts → Telegram Queue: queues messages
- Portfolio Records → Local JSON Mirrors: mirrors records
- Portfolio Records → Supabase: reads and writes
- Streamlit Dashboard → Dashboard Components: renders views
- Streamlit Dashboard → Terminal Styling: styles interface
- Streamlit Dashboard → Market Data Fetcher: loads market data
- Streamlit Dashboard → Signal Scoring: shows analysis
- Streamlit Dashboard → Portfolio Records: reads portfolio
- Signal Scoring → Dark Pool Detection: uses detection
- Signal Scoring → Black Swan Alarm: uses alarm
- Signal Scoring → Sector Rotation: uses sector analysis
- News Intelligence → Market Data APIs: collects news