# youcef3939/oracle architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/oracle
- Repository: https://github.com/youcef3939/oracle

## Overview

1. **What this repository is**
   ORACLE is a Python 3.10+ market-regime detection system. Architecturally it is split into two top-level surfaces: a reusable detection pipeline in `src/` and a Streamlit dashboard in `dashboard/app.py`. The system is designed for financial time-series rather than generic web requests.

2. **Primary entrypoints**
   The main programmatic boundary is the `MarketRegimeDetector`-style workflow described in the README and implemented across `src/regime_detector.py` plus the supporting modules. The user-facing interactive entrypoint is the Streamlit app, which reads results from the core pipeline and renders charts and summaries.

3. **Data acquisition layer**
   `src/data_fetcher.py` is the ingestion boundary. Its job is to pull raw market data for multiple assets and produce the input dataset used by the rest of the pipeline. The README indicates external sources such as `yfinance`, so the architecture likely depends on remote market-data APIs rather than an internal datastore.

4. **Preprocessing layer**
   `src/preprocessing.py` is where raw time series are cleaned and made model-ready. This is the normalization/alignment/resampling boundary: it turns heterogeneous asset series into a consistent panel that downstream feature extraction and modeling can consume.

5. **Feature engineering layer**
   `src/features.py` converts preprocessed market data into domain signals such as returns, volatility, momentum, and correlations. This is the main transformation layer between normalized time series and learned representations, and it is where cross-asset relationships become explicit inputs.

6. **Model core**
   `src/model_core.py` contains the learning backbone. Based on the README, the core supports deep sequence models such as Transformers and VAE-style encoders that compress market behavior into latent embeddings. This is the boundary where the repository moves from engineered indicators to learned market-state representations.

7. **Regime detection orchestration**
   `src/regime_detector.py` is the central coordinator. It ties together fetching, preprocessing, feature generation, model inference/training, and regime assignment. This is the logical “application service” of the repo: the part that exposes fit/predict-style behavior and turns latent outputs into discrete regimes.

8. **Prediction/forecasting layer**
   `src/predictive.py` is a separate forward-looking module for regime probabilities or short-horizon forecasts. It sits downstream of the detector and is used when the system needs not just current regime labels, but expected transitions or confidence estimates.

9. **Visualization layer**
   `src/visualization.py` prepares plots and analytical views for the dashboard. It is the reporting boundary that translates regime timelines, embeddings, correlations, and probabilities into visual artifacts rather than raw data structures.

10. **Dashboard boundary**
   `dashboard/app.py` is the interactive presentation layer built with Streamlit. It does not appear to own model logic; instead, it orchestrates the core modules and visualization helpers to present regime analysis, predictions, and scenario-style views to the user.

11. **End-to-end data flow**
   The architectural flow is: external market data in → fetcher → preprocessing → feature engineering → model core embedding → regime detection/classification → predictive scoring and visualization. The output is a regime label stream plus probabilities/metrics that the dashboard renders.

12. **Important architectural boundaries**
   The repo cleanly separates: data acquisition, data conditioning, feature construction, model inference, regime interpretation, and presentation. That separation is important for diagramming because each stage can change independently without rewriting the dashboard or the ingestion layer.

13. **Persistence and deployment posture**
   There is no obvious database, message bus, or server-side API in the tree. That suggests a mostly local, in-memory analytical application with optional saved model artifacts rather than a distributed system. The main runtime surfaces are a Python library and a Streamlit app.

Main entry points: [`src/regime_detector.py`](https://github.com/youcef3939/oracle/blob/main/src/regime_detector.py) (Detector), [`src/visualization.py`](https://github.com/youcef3939/oracle/blob/main/src/visualization.py) (Visuals), [`src/data_fetcher.py`](https://github.com/youcef3939/oracle/blob/main/src/data_fetcher.py) (Fetcher), [`src/preprocessing.py`](https://github.com/youcef3939/oracle/blob/main/src/preprocessing.py) (Preprocess)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core pipeline"]
  node_data_fetcher["Fetcher<br/>ingestion<br/>[data_fetcher.py]"]
  node_preprocessing["Preprocess<br/>conditioning<br/>[preprocessing.py]"]
  node_features["Features<br/>engineering<br/>[features.py]"]
  node_model_core{{"Model core<br/>sequence model<br/>[model_core.py]"}}
  node_regime_detector["Detector<br/>orchestration<br/>[regime_detector.py]"]
  node_predictive["Predictive<br/>forecasting<br/>[predictive.py]"]
  node_visualization["Visuals<br/>reporting<br/>[visualization.py]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard_app["Dashboard app<br/>streamlit ui<br/>[app.py]"]
end

node_market_data[("Market data<br/>external source")]

node_market_data -->|"source"| node_data_fetcher
node_data_fetcher -->|"raw data"| node_preprocessing
node_preprocessing -->|"prepared series"| node_features
node_features -->|"signals"| node_model_core
node_model_core -->|"embeddings"| node_regime_detector
node_regime_detector -->|"regimes"| node_predictive
node_regime_detector -->|"outputs"| node_visualization
node_predictive -->|"forecasts"| node_visualization
node_visualization -->|"views"| node_dashboard_app
node_regime_detector -->|"analysis"| node_dashboard_app

click node_data_fetcher "https://github.com/youcef3939/oracle/blob/main/src/data_fetcher.py"
click node_preprocessing "https://github.com/youcef3939/oracle/blob/main/src/preprocessing.py"
click node_features "https://github.com/youcef3939/oracle/blob/main/src/features.py"
click node_model_core "https://github.com/youcef3939/oracle/blob/main/src/model_core.py"
click node_regime_detector "https://github.com/youcef3939/oracle/blob/main/src/regime_detector.py"
click node_predictive "https://github.com/youcef3939/oracle/blob/main/src/predictive.py"
click node_visualization "https://github.com/youcef3939/oracle/blob/main/src/visualization.py"
click node_dashboard_app "https://github.com/youcef3939/oracle/blob/main/dashboard/app.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_data_fetcher,node_preprocessing,node_features,node_model_core,node_regime_detector,node_predictive,node_visualization toneBlue
class node_dashboard_app toneAmber
class node_market_data toneNeutral
```

## Components

### Core pipeline

Reusable market-regime detection and forecasting workflow.

- [Fetcher](https://github.com/youcef3939/oracle/blob/main/src/data_fetcher.py): ingestion · Retrieves raw asset data and assembles the input dataset. · `src/data_fetcher.py`
- [Preprocess](https://github.com/youcef3939/oracle/blob/main/src/preprocessing.py): conditioning · Cleans, aligns, and normalizes heterogeneous time-series panels. · `src/preprocessing.py`
- [Features](https://github.com/youcef3939/oracle/blob/main/src/features.py): engineering · Builds returns, volatility, momentum, and correlation signals. · `src/features.py`
- [Model core](https://github.com/youcef3939/oracle/blob/main/src/model_core.py): sequence model · Learns latent market-state representations with deep encoders. · `src/model_core.py`
- [Detector](https://github.com/youcef3939/oracle/blob/main/src/regime_detector.py): orchestration · Coordinates the end-to-end fit and regime assignment workflow. · `src/regime_detector.py`
- [Predictive](https://github.com/youcef3939/oracle/blob/main/src/predictive.py): forecasting · Produces regime probabilities and short-horizon transition signals. · `src/predictive.py`
- [Visuals](https://github.com/youcef3939/oracle/blob/main/src/visualization.py): reporting · Prepares charts and analytical views for regime interpretation. · `src/visualization.py`

### Dashboard

Streamlit presentation layer for interactive analysis.

- [Dashboard app](https://github.com/youcef3939/oracle/blob/main/dashboard/app.py): streamlit ui · Interactive UI that renders regimes, forecasts, and summaries. · `dashboard/app.py`

### Other components

- **Market data**: external source · Remote financial time-series inputs used by the pipeline.

## Connections

- Market data → Fetcher: source · External market feeds are pulled into the pipeline.
- Fetcher → Preprocess: raw data · Fetched assets are cleaned and aligned for modeling.
- Preprocess → Features: prepared series · Normalized panels feed feature construction.
- Features → Model core: signals · Engineered indicators are encoded into latent state.
- Model core → Detector: embeddings · Latent representations drive regime labeling.
- Detector → Predictive: regimes · Detected states are used for probabilities and forecasts.
- Detector → Visuals: outputs · Regime timelines and metrics are prepared for display.
- Predictive → Visuals: forecasts · Prediction outputs are turned into charts and summaries.
- Visuals → Dashboard app: views · Prepared plots are rendered in the Streamlit app.
- Detector → Dashboard app: analysis · The dashboard orchestrates the core detector workflow.
