# zdanovic/insurane_claim architecture

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

- Interactive diagram: https://gitdiagram.com/zdanovic/insurane_claim
- Repository: https://github.com/zdanovic/insurane_claim

## Overview

##### Project type and purpose
- This is an offline, two-stage machine-learning pipeline for insurance claim forecasting (initial reserve at FNOL and final loss modeling).
- It runs as a series of Jupyter notebooks, ingesting CSV data, performing EDA, training models, evaluating performance, and producing interpretability outputs.

##### File structure
- data/ (CSV data stores for policies, raw claims, merged data)
- notebooks/
– 01_preprocessing_eda.ipynb (data cleaning, feature engineering, EDA)
– 02_fnol_model.ipynb (train & compare GLM Tweedie and XGBoost for FNOL reserves)
– 03_final_loss_model.ipynb (train final loss models, ensemble stacking)
- README.md, .gitignore (repo metadata)

##### Extract insights from README
- Two sequential modeling stages with strict no-leakage rules
- Ensemble approach combining statistical (GLM Tweedie) and ML (XGBoost)
- Interpretability via SHAP and error-case analysis
- Targets: MAE, RMSE, R² across two forecast horizons

##### Main components
a. Data Storage
– Raw CSV files (policies, claims)
– Merged/processed dataset
b. Preprocessing & EDA Module
– Notebook 01: cleaning, transforms, rolling windows, encoding
c. FNOL Modeling Module
– Notebook 02: GLM Tweedie vs. XGBoost training & validation
d. Final Loss Modeling Module
– Notebook 03: ingest FNOL outputs + features, train ensemble (Stacking Regressor)
e. Evaluation & Interpretability
– Metrics calculation (MAE, RMSE, R²)
– SHAP feature-importance plots, error case visuals
f. Downstream Integration
– Exported model artifacts & reports for dashboards/audit pipelines
g. Execution Environment
– Jupyter Notebook server, Python 3.8+, key libs (pandas, scikit-learn, xgboost, shap, matplotlib)

##### Relationships and data flows
1. Raw Data → Preprocessing & EDA
2. Processed Data → FNOL Modeling
3. FNOL Predictions + Features → Final Loss Modeling
4. Model Outputs → Evaluation & Interpretability
5. Artifacts & Visuals → Downstream Integration

##### Architectural patterns & principles
- Two-stage sequential pipeline (FNOL → Final Loss)
- Modular notebooks as components
- Strict data-leakage controls
- Ensemble design pattern (stacking regressors)
- Interpretability baked into pipeline (SHAP)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Jupyter Environment (Python 3.8+, pandas, scikit-learn, xgboost, shap, matplotlib)"
        direction TB
        RawData["Raw CSV Data\n(policies, claims)"]:::datastore
        ProcessedData["Processed Dataset"]:::datastore
        Preprocessing["Preprocessing & EDA\n(Notebook 01)"]:::processing
        FNOL["FNOL Modeling\n(Notebook 02)"]:::processing
        FinalLoss["Final Loss Modeling\n(Notebook 03)"]:::processing
        Evaluation["Evaluation & Interpretability\n(MAE, RMSE, R², SHAP)"]:::evaluation
        Integration["Model Artifacts & Reports"]:::integration
    end

    subgraph "Project Files"
        direction TB
        README["README.md"]:::meta
        Gitignore[".gitignore"]:::meta
    end

    RawData -->|ingest| Preprocessing
    Preprocessing -->|produces| ProcessedData
    ProcessedData -->|feeds| FNOL
    FNOL -->|predictions & features| FinalLoss
    FinalLoss -->|model outputs| Evaluation
    Evaluation -->|artifacts & visuals| Integration

    click Preprocessing "https://github.com/zdanovic/insurane_claim/blob/main/notebooks/01_preprocessing_eda.ipynb"
    click FNOL "https://github.com/zdanovic/insurane_claim/blob/main/notebooks/02_fnol_model.ipynb"
    click FinalLoss "https://github.com/zdanovic/insurane_claim/blob/main/notebooks/03_final_loss_model.ipynb"
    click README "https://github.com/zdanovic/insurane_claim/blob/main/README.md"
    click Gitignore "https://github.com/zdanovic/insurane_claim/blob/main/.gitignore"

    classDef datastore fill:#D0E1F9,stroke:#333,stroke-width:1px
    classDef processing fill:#C6EFD7,stroke:#333,stroke-width:1px
    classDef evaluation fill:#F9D7B9,stroke:#333,stroke-width:1px
    classDef integration fill:#E0BBE4,stroke:#333,stroke-width:1px
    classDef meta fill:#F0F0F0,stroke:#333,stroke-width:1px
```
