# 19vermouth/oilpricemonitor architecture

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

- Interactive diagram: https://gitdiagram.com/19vermouth/oilpricemonitor
- Repository: https://github.com/19vermouth/oilpricemonitor

## Overview

##### Project Type and Purpose
- This is a full-stack Python application for real-time Oil Price Monitoring & Analysis.
- Purpose:
- Ingest live oil price and news data from multiple APIs
- Detect anomalies in price feeds
- Correlate anomalies with news events
- Generate AI-driven summaries and insights
- Expose results via a Streamlit dashboard

##### File Structure
Top-level files & folders:
- chatbot.py, dashboard.py, test_env.py: entry points for UI/interaction/testing.
- data/: local SQLite database scripts (init_db.py, sampledb.py).
- src/: core modules orchestrating data ingestion, processing, AI analysis.
- price_tracker.py
- anomaly_detector.py
- news_aggregator.py
- ollama_analyzer.py
- etl_pipeline.py
- monitor.py
- utils/: shared configuration and logger.
- requirements.txt, .gitignore.

Architectural Patterns:
- Modular pipeline: source connectors → anomaly detection → AI analysis → storage.
- Orchestrator module (monitor.py) invokes subcomponents.
- Separation of concerns: data ingestion, processing, AI, UI.

##### README for Additional Insights
- Tech stack: Python, SQLite, Streamlit, Plotly, Statsmodels, Ollama/Mistral-7B.
- Multi-source resilience, local cache fallback.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External APIs"
        direction TB
        EX1["Alpha Vantage"]:::external
        EX2["yFinance"]:::external
        EX3["NewsAPI/GNews"]:::external
    end

    %% Orchestrator & Ingestion & Processing
    subgraph "Pipeline Orchestration & Processing"
        direction TB
        MON["Monitor (Orchestrator)\n(polling interval)"]:::processing
        PT["Price Tracker"]:::processing
        AD["Anomaly Detector\n(z-score threshold)"]:::processing
        NA["News Aggregator"]:::processing
        ETL["ETL Pipeline\n(Storage Orchestration)"]:::processing
    end

    %% AI Analysis Layer
    subgraph "AI Analysis"
        direction TB
        OA["Ollama Analyzer"]:::ai
        LLM["Ollama LLM Server"]:::ai
    end

    %% Storage Layer
    subgraph "Data Storage"
        direction TB
        DB["SQLite Database"]:::db
    end

    %% Presentation/UI Layer
    subgraph "Presentation/UI"
        direction TB
        Dash["Streamlit Dashboard"]:::ui
        Chat["Chatbot Interface"]:::ui
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        CFG["Configuration Manager"]:::util
        LOG["Centralized Logger"]:::util
        TestEnv["Test Environment Bootstrap"]:::util
    end

    %% Connections
    EX1 -->|fetch price| PT
    EX2 -->|fetch price| PT
    MON -->|trigger| PT
    PT -->|send data| AD
    AD -->|anomaly detected| NA
    AD -->|no anomaly| ETL
    EX3 -->|fetch news| NA
    NA -->|news feed| OA
    OA -->|LLM query| LLM
    OA -->|analysis output| ETL
    ETL -->|write| DB
    DB -->|read| Dash
    OA -->|insights| Dash
    DB -->|read| Chat

    %% Utilities connections (dotted)
    CFG -.-> MON
    CFG -.-> PT
    CFG -.-> AD
    CFG -.-> NA
    CFG -.-> ETL
    CFG -.-> OA
    CFG -.-> Dash
    CFG -.-> Chat

    LOG -.-> MON
    LOG -.-> PT
    LOG -.-> AD
    LOG -.-> NA
    LOG -.-> ETL
    LOG -.-> OA
    LOG -.-> Dash
    LOG -.-> Chat

    TestEnv -.-> MON

    %% Click Events
    click PT "https://github.com/19vermouth/oilpricemonitor/blob/main/src/price_tracker.py"
    click NA "https://github.com/19vermouth/oilpricemonitor/blob/main/src/news_aggregator.py"
    click AD "https://github.com/19vermouth/oilpricemonitor/blob/main/src/anomaly_detector.py"
    click ETL "https://github.com/19vermouth/oilpricemonitor/blob/main/src/etl_pipeline.py"
    click OA "https://github.com/19vermouth/oilpricemonitor/blob/main/src/ollama_analyzer.py"
    click MON "https://github.com/19vermouth/oilpricemonitor/blob/main/src/monitor.py"
    click DB "https://github.com/19vermouth/oilpricemonitor/blob/main/data/init_db.py"
    click Dash "https://github.com/19vermouth/oilpricemonitor/blob/main/dashboard.py"
    click CFG "https://github.com/19vermouth/oilpricemonitor/blob/main/utils/config.py"
    click LOG "https://github.com/19vermouth/oilpricemonitor/blob/main/utils/logger.py"
    click Chat "https://github.com/19vermouth/oilpricemonitor/blob/main/chatbot.py"
    click TestEnv "https://github.com/19vermouth/oilpricemonitor/blob/main/test_env.py"

    %% Styles
    classDef external fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef processing fill:#d4edda,stroke:#28a745,color:#000;
    classDef ai fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef ui fill:#e6e0f8,stroke:#8a2be2,color:#000;
    classDef util fill:#f0e5d8,stroke:#cd7f32,color:#000;
```
