---
sidebar_position: 3
---

# L3 — Components

> **C4 Level 3**: Zooms into the key containers and shows their internal modules, classes, and responsibilities.

:::info C4 Model — Level 3
The Component diagram answers: *What are the major structural elements inside each container?*
:::

## Analysis Engine — Component Diagram

```mermaid
C4Component
    title Components — Analysis Engine

    Container_Ext(tsdb, "Market Data Store", "SQLite / TimescaleDB", "OHLCV candles")
    Container_Ext(signalGen, "Signal Generator", "Python", "Consumes indicator snapshots")

    Container_Boundary(analyser, "Analysis Engine") {
        Component(candleLoader, "Candle Loader", "pandas", "Loads recent OHLCV windows from DB for each symbol and timeframe.")
        Component(trendEngine, "Trend Engine", "pandas-ta", "Computes EMA, MACD, ADX, Parabolic SAR.")
        Component(momentumEngine, "Momentum Engine", "pandas-ta", "Computes RSI, Stochastic, CCI, Williams %R.")
        Component(volatilityEngine, "Volatility Engine", "pandas-ta", "Computes Bollinger Bands, ATR, Keltner Channels.")
        Component(volumeEngine, "Volume Engine", "pandas-ta", "Computes VWAP, OBV, Volume Profile.")
        Component(patternRecog, "Pattern Recogniser", "ta-lib / custom", "Detects candlestick and chart patterns.")
        Component(confluenceScorer, "Confluence Scorer", "Python", "Weights and combines indicator signals into a 0–1 confluence score.")
        Component(snapshotWriter, "Snapshot Writer", "pandas / SQLAlchemy", "Persists indicator snapshots to DB for the signal generator.")
    }

    Rel(candleLoader, tsdb, "Reads OHLCV", "SQL")
    Rel(trendEngine, candleLoader, "Reads candle frame")
    Rel(momentumEngine, candleLoader, "Reads candle frame")
    Rel(volatilityEngine, candleLoader, "Reads candle frame")
    Rel(volumeEngine, candleLoader, "Reads candle frame")
    Rel(patternRecog, candleLoader, "Reads candle frame")
    Rel(confluenceScorer, trendEngine, "Reads signals")
    Rel(confluenceScorer, momentumEngine, "Reads signals")
    Rel(confluenceScorer, volatilityEngine, "Reads signals")
    Rel(confluenceScorer, volumeEngine, "Reads signals")
    Rel(confluenceScorer, patternRecog, "Reads patterns")
    Rel(snapshotWriter, confluenceScorer, "Reads scored snapshot")
    Rel(snapshotWriter, tsdb, "Writes snapshots", "SQL")
    Rel(signalGen, snapshotWriter, "Reads snapshots", "SQL")
```

## Signal Generator — Component Diagram

```mermaid
C4Component
    title Components — Signal Generator

    Container_Ext(tsdb, "Market Data Store", "TimescaleDB", "Indicator snapshots")
    Container_Ext(newsApi, "Economic Calendar API", "REST", "High-impact events")
    Container_Ext(notifier, "Notifier", "Python", "Receives final signals")

    Container_Boundary(signalGen, "Signal Generator") {
        Component(snapshotReader, "Snapshot Reader", "SQLAlchemy", "Loads latest indicator snapshots per symbol.")
        Component(biasFilter, "Bias Filter", "Python", "Determines directional bias (bullish/bearish/neutral) per pair from higher-TF trend.")
        Component(setupScanner, "Setup Scanner", "Python", "Identifies candidate setups where confluence score ≥ 0.65.")
        Component(riskCalc, "Risk Calculator", "Python", "Calculates entry, stop-loss, take-profit; validates R:R ≥ 1.5.")
        Component(newsFilter, "News Filter", "Python / requests", "Rejects signals within 30 min of high-impact economic events.")
        Component(correlFilter, "Correlation Filter", "Python", "Prevents conflicting signals on correlated pairs (e.g. EUR/USD + GBP/USD both long).")
        Component(dailyLimitGuard, "Daily Limit Guard", "Python", "Enforces max 3 signals per day hard cap.")
        Component(signalAssembler, "Signal Assembler", "Python", "Packages final signals with metadata, reasoning, and time window.")
    }

    Rel(snapshotReader, tsdb, "Reads snapshots", "SQL")
    Rel(biasFilter, snapshotReader, "Reads higher-TF data")
    Rel(setupScanner, snapshotReader, "Reads scored snapshots")
    Rel(setupScanner, biasFilter, "Applies directional filter")
    Rel(riskCalc, setupScanner, "Calculates levels per setup")
    Rel(newsFilter, newsApi, "Fetches upcoming events", "REST")
    Rel(newsFilter, riskCalc, "Filters out news-window setups")
    Rel(correlFilter, newsFilter, "Deduplicates correlated setups")
    Rel(dailyLimitGuard, correlFilter, "Enforces ≤3 cap")
    Rel(signalAssembler, dailyLimitGuard, "Assembles final signals")
    Rel(notifier, signalAssembler, "Receives signals for delivery")
```

## Data Ingestor — Component Breakdown

| Component | Responsibility |
|---|---|
| **Source Router** | Selects primary/fallback data source per symbol |
| **REST Poller** | Fetches 1m candles from REST API on schedule |
| **WS Stream Client** | Maintains WebSocket connection for real-time tick data |
| **Normaliser** | Maps source-specific field names → unified OHLCV schema |
| **Gap Detector** | Identifies missing candles, triggers backfill |
| **Backfiller** | Fetches historical data to fill detected gaps |
| **Rate Limiter** | Tracks and respects per-API-key rate limits |
| **Health Reporter** | Emits data freshness metrics; alerts on stale data |

## Confluence Scoring — Detail

```python
# Scoring weights (sum = 1.0)
WEIGHTS = {
    'trend_alignment':  0.30,   # EMA cross, MACD, ADX
    'momentum':         0.25,   # RSI, Stochastic, CCI
    'volume':           0.20,   # VWAP, OBV
    'pattern':          0.15,   # Candlestick / chart patterns
    'key_level':        0.10,   # Support/resistance proximity
}

MINIMUM_CONFLUENCE = 0.65   # Hard threshold
MINIMUM_RR_RATIO   = 1.5    # Risk/reward hard floor
MAX_DAILY_SIGNALS  = 3      # Hard daily cap
MAX_HOLD_MINUTES   = 30     # Hard position time limit
```