# solalbaudoincs/ifcob architecture

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

- Interactive diagram: https://gitdiagram.com/solalbaudoincs/ifcob
- Repository: https://github.com/solalbaudoincs/ifcob

## Overview

##### Project type and purpose
- This is a research‐oriented, modular analytics framework (not a web application).
- Purpose: process high‐frequency crypto order‐book data, extract predictive features, train multiple models, and evaluate custom trading strategies via event‐driven backtesting.

##### File structure
- Top‐level orchestration scripts: main.py, backtesting_example.py, scripts/, found_documentation.md
- Modules:
- preprocessing/: raw CSV → cleaned, deduplicated, wide‐format parquet
- feature_extraction/: compute order‐book features (imbalance, slope, volatility, etc.)
- prediction_model/: notebook‐driven model experiments + model_manager.py
- predictors/: serialized model artifacts (.joblib + perf.json)
- backtesting/: event‐driven engine, Strategy base class, portfolio & order processing
- perf_analysis/: post‐backtest performance analysis
- strategies/: strategy implementations (trend_following, linear_regression, rf, etc.)
- Support: requirements.txt, LICENSE, README files per module

##### README for additional insights
- Describes a pipeline: data preprocessing → feature extraction → model training & selection → backtesting → performance metrics.
- Highlights modular design, custom strategy support, and realistic transaction cost modeling.

1. Raw Data Ingestion
2. Preprocessing Module
3. Feature Extraction Module
4. Model Training & Management
5. Model Repository (predictors/)
6. Backtesting Engine
7. Strategies Library
8. Performance Analysis
9. Orchestration Scripts / CLI
- Raw Data → Preprocessing → Preprocessed Data
- Preprocessed Data → Feature Extraction → Feature Store (e.g., parquet, JSON)
- Feature Store → Model Training → Trained Models → Model Repository
- Model Repository + Feature Store → Backtesting Engine ← Strategies Library
- Backtesting Engine → Backtest Results → Performance Analysis → Reports/Plots
- Orchestration Scripts invoke each step in sequence or individually
c. Architectural patterns & principles:
- Pipeline / ETL pattern for data flow
- Plugin architecture: custom strategy classes conform to Strategy interface
- Separation of concerns: data prep, feature gen, modeling, backtesting, and analysis are distinct modules
- Artifact management: serialized models + perf metadata in predictors/
d. Key technologies & frameworks:
- Python modules & scripts, Jupyter notebooks for exploration
- pandas, numpy for data manipulation
- scikit‐learn / XGBoost / AdaBoost for modeling
- joblib for model serialization
- Custom backtesting engine in backtesting/
- JSON for feature metadata and perf stats

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Input & Preprocessing
    subgraph "Data Input & Preprocessing"
        RawCSV["Raw CSV Data"]:::datastore
        PreprocessedData["Preprocessed Data (Parquet)"]:::datastore
        subgraph Preprocessing_Module
            DP["data_preprocessor.py"]:::process
            PS["preprocess_script.py"]:::process
            EU["example_usage.py"]:::process
            SP["preprocess_all_data.py"]:::orchestration
        end
        RawCSV --> Preprocessing_Module
        Preprocessing_Module --> PreprocessedData
    end
    click DP "https://github.com/solalbaudoincs/ifcob/blob/main/preprocessing/data_preprocessor.py"
    click PS "https://github.com/solalbaudoincs/ifcob/blob/main/preprocessing/preprocess_script.py"
    click EU "https://github.com/solalbaudoincs/ifcob/blob/main/preprocessing/example_usage.py"
    click SP "https://github.com/solalbaudoincs/ifcob/blob/main/scripts/preprocess_all_data.py"

    %% Feature Extraction
    subgraph "Feature Extraction"
        FE["Feature Extraction Module"]:::process
        FeatureStore["Feature Store (Parquet/JSON)"]:::datastore
        subgraph FE_Files
            FG["feature_generator.py"]:::process
            FB["base.py"]:::process
            FList["features/*.py"]:::process
        end
        PreprocessedData --> FE
        FE --> FeatureStore
    end
    click FG "https://github.com/solalbaudoincs/ifcob/blob/main/feature_extraction/feature_generator.py"
    click FB "https://github.com/solalbaudoincs/ifcob/blob/main/feature_extraction/base.py"
    click FList "https://github.com/solalbaudoincs/ifcob/tree/main/feature_extraction/features"

    %% Model Training & Management
    subgraph "Model Training & Management"
        MT["Model Training Module"]:::process
        TrainedModels["Trained Models"]:::datastore
        subgraph MT_Files
            MM["model_manager.py"]:::process
            MDP["data_preprocess.py"]:::process
            NB["*_notebook.ipynb"]:::process
        end
        FeatureStore --> MT
        MT --> TrainedModels
        TrainedModels --> ModelRepo
    end
    click MM "https://github.com/solalbaudoincs/ifcob/blob/main/prediction_model/model_manager.py"
    click MDP "https://github.com/solalbaudoincs/ifcob/blob/main/prediction_model/data_preprocess.py"
    click NB "https://github.com/solalbaudoincs/ifcob/tree/main/prediction_model"

    %% Model Repository
    ModelRepo["Model Repository (predictors/)"]:::datastore
    click ModelRepo "https://github.com/solalbaudoincs/ifcob/tree/main/predictors"

    %% Strategies Library
    subgraph "Strategies Library"
        Strategies["Strategies"]:::process
        subgraph Strat_Files
            TF["trend_following.py"]:::process
            LR["linear_regression.py"]:::process
            RF["rf_pred_all_signed_strat_mateo.py"]:::process
            M2["mateo_2_start.py"]:::process
        end
    end
    click TF "https://github.com/solalbaudoincs/ifcob/blob/main/strategies/trend_following.py"
    click LR "https://github.com/solalbaudoincs/ifcob/blob/main/strategies/linear_regression.py"
    click RF "https://github.com/solalbaudoincs/ifcob/blob/main/strategies/rf_pred_all_signed_strat_mateo.py"
    click M2 "https://github.com/solalbaudoincs/ifcob/blob/main/strategies/mateo_2_start.py"

    %% Backtesting Engine
    subgraph "Backtesting Engine"
        BE["Backtesting Engine"]:::process
        BacktestResults["Backtest Results"]:::datastore
        subgraph BE_Files
            BC["backtest.py"]:::process
            DL["dataloader.py"]:::process
            OP["order_processor.py"]:::process
            PF["portfolio.py"]:::process
            ST["strategy.py"]:::process
            TY["types.py"]:::process
        end
        FeatureStore --> BE
        ModelRepo --> BE
        Strategies --> BE
        BE --> BacktestResults
    end
    click BC "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/backtest.py"
    click DL "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/dataloader.py"
    click OP "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/order_processor.py"
    click PF "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/portfolio.py"
    click ST "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/strategy.py"
    click TY "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting/types.py"

    %% Performance Analysis
    subgraph "Performance Analysis"
        PA["perf_analysis.py"]:::process
        Reports["Reports/Plots"]:::datastore
        BacktestResults --> PA
        PA --> Reports
    end
    click PA "https://github.com/solalbaudoincs/ifcob/blob/main/perf_analysis/perf_analysis.py"

    %% Orchestration Scripts / CLI
    subgraph "Orchestration Scripts / CLI"
        Main["main.py"]:::orchestration
        BEx["backtesting_example.py"]:::orchestration
        CF["create_feature.py"]:::orchestration
        GF["generate_features.py"]:::orchestration
        MMm["manage_models.py"]:::orchestration
    end
    click Main "https://github.com/solalbaudoincs/ifcob/blob/main/main.py"
    click BEx "https://github.com/solalbaudoincs/ifcob/blob/main/backtesting_example.py"
    click CF "https://github.com/solalbaudoincs/ifcob/blob/main/scripts/create_feature.py"
    click GF "https://github.com/solalbaudoincs/ifcob/blob/main/scripts/generate_features.py"
    click MMm "https://github.com/solalbaudoincs/ifcob/blob/main/scripts/manage_models.py"

    %% Orchestration flows
    Main --> Preprocessing_Module
    Main --> FE
    Main --> MT
    Main --> BE
    Main --> PA

    %% Styling
    classDef datastore fill:#ADD8E6,stroke:#000;
    classDef process fill:#90EE90,stroke:#000;
    classDef orchestration fill:#FFA500,stroke:#000;
```
