# tergelitu/teda-v1 architecture

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

- Interactive diagram: https://gitdiagram.com/tergelitu/teda-v1
- Repository: https://github.com/tergelitu/teda-v1

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **Python analytics library/package** (not a service). Its purpose is **Temporal Exploratory Data Analysis** and **feature drift monitoring** over time, offering functions that:
- compute feature summary metrics (missingness, uniqueness, volatility, correlation)
- track drift (PSI) monthly
- detect structural breaks (ruptures)
- track feature importance evolution (RF/XGBoost)
- decompose series into trend/seasonality/residual (HP filter via statsmodels)

##### File structure analysis (what components exist)
From the tree:

- `teda/` — the actual Python package
- `teda/__init__.py` — defines the **public API surface** (what `import teda as te` exposes)
- `teda/features.py` — appears to contain **core implementations** of the features listed in the README (overview_table, PSI, PCA plot, change points, importance, HP filter plots)
- `pyproject.toml` — packaging/build metadata (dependencies, versioning, distribution)
- `README.md` — functional scope and user-facing API
- `.gitignore`, `LICENSE` — not architectural

This implies a relatively simple internal architecture: **single-module core** with multiple functions, mediated by `__init__.py`.

##### README-derived architecture clues (stack & runtime)
- **pandas/numpy**: data handling + numeric ops (central)
- **plotly** (+ ipywidgets): interactive visual outputs, notebook UX
- **scikit-learn**: preprocessing/PCA, RandomForest
- **xgboost**: feature importance evolution
- **ruptures**: changepoint detection algorithms (PELT/Binseg/Dynp)
- **statsmodels**: HP filter decomposition

##### User / Consumer Environment
- “Data Scientist / ML Engineer”
- “Jupyter Notebook / Python Script”
- `teda-demo.ipynb` (example consumer)

##### Inputs
- “Dataset (pandas DataFrame)”
- includes `date_col`, optional `target_col`, optional `exclude_cols`
- Optional: “Configuration/Parameters”
- thresholds (PSI), model choice (ruptures algorithm), etc.

##### TEDA Package (the library itself)
Inside a boundary labeled `teda`:
- **Public API layer**: `teda/__init__.py`
- exposes: `overview_table`, `plot_monthly_psi`, `plot_monthly_pca`, `detect_change_points`, `plot_monthly_importance`, `plot_monthly_trend`
- **Core implementation**: `teda/features.py`
- implement the computation + plotting
- “Temporal aggregation (monthly)”
- “Feature stats & drift metrics”
- “Modeling (PCA / RF / XGB)”
- “Changepoint detection”
- “Trend decomposition (HP filter)”

##### External Dependencies (libraries)
- pandas/numpy (used by essentially every function)
- plotly (+ ipywidgets) for visualizations
- scikit-learn (PCA, RandomForest, preprocessing)
- xgboost (importance evolution model)
- ruptures (changepoint detection)
- statsmodels (HP filter)

##### Outputs
- “Tables / DataFrames” (overview outputs, metrics tables)
- “Plots / Interactive Figures” (plotly)
- “Warnings/Threshold alerts” (PSI threshold warnings)

Model the interactions as a **call/dataflow pipeline**:

**User/Notebook** → calls **Public API (`__init__.py`)** → delegates to **features.py** → uses **pandas/numpy** and the specialized libs → returns:
- a DataFrame-like table and/or
- a plotly Figure rendered in notebook and/or
- warning signals (threshold flags)

Critically, show that the **DataFrame is the central artifact** flowing through:
- preprocessing (exclude cols, parse date)
- monthly aggregation
- metric/model computations
- visualization

##### Architectural patterns / design principles

- **Library / functional API**: functions are the unit of composition (not long-running services).
- **Thin public API, thick implementation module**: `__init__.py` re-exports core functions; `features.py` contains logic.
- **Pipeline stages** repeated across features:
- “time aggregation” → “computation” → “visualization/report”
- **Dependency-driven capability modules**:
- drift (PSI) ↔ stats
- PCA ↔ scikit-learn
- breakpoints ↔ ruptures
- importance ↔ sklearn/xgboost
- trend ↔ statsmodels

- PSI tracking: pandas/numpy (PSI implementation), plotly (line chart), warning thresholds
- PCA 3D: scikit-learn PCA, plotly 3D scatter, monthly means + distance calc
- Change points: ruptures (PELT/Binseg/Dynp), plotly markers
- Feature importance evolution: RandomForest (sklearn) / XGBoost, rolling/monthly training, plotly
- HP filter: statsmodels HP filter, plotly decomposition plots
- Overview table: pandas/numpy stats + correlation with target

##### Tier 1 (Consumer + Input)
- Jupyter Notebook / Python Script (`teda-demo.ipynb`)
→ DataFrame (pandas)

##### Tier 2 (TEDA internals)
- `teda` package boundary
- `__init__.py` (Public API)
→ `features.py` (Implementations)
- shared step: “Monthly aggregation”

##### Tier 3 (Dependencies + Output)
- Dependencies: pandas/numpy, plotly/ipywidgets, sklearn, xgboost, ruptures, statsmodels
- Outputs: “Overview Table (DataFrame)”, “PSI Time Series Plot”, “3D PCA Plot + Distance Bars”, “Breakpoint Plot”, “Importance Evolution Plot”, “Trend/Seasonality/Residual Plot”

This will be the most accurate representation given the small codebase and the README-defined API.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Tier 1: Consumer + Inputs
%% =========================
subgraph "Consumer Environment"
  DS["Data Scientist / ML Engineer"]:::actor
  NB["Jupyter Notebook / Python Script"]:::consumer
  DEMO["teda-demo.ipynb (Reference Consumer)"]:::consumer
end

subgraph "Inputs"
  DF[/"Dataset (pandas DataFrame)\n(date_col, optional target_col, exclude_cols)"/]:::input
  CFG[/"Parameters / Config\n(PSI thresholds, ruptures algorithm, model choices)"/]:::input
end

DS -->|"runs"| NB
DEMO -->|"example_usage"| NB
NB -->|"provides"| DF
NB -->|"sets"| CFG

%% =========================
%% Tier 2: TEDA Package
%% =========================
subgraph "TEDA Package (Python Library)"
  PKG["teda (package boundary)"]:::pkg

  subgraph "Public API"
    INIT["teda/__init__.py\n(Thin public API: re-exports functions)"]:::module
    API_LIST["Public Functions\n- overview_table\n- plot_monthly_psi\n- plot_monthly_pca\n- detect_change_points\n- plot_monthly_importance\n- plot_monthly_trend"]:::api
  end

  subgraph "Core Implementation"
    FEAT["teda/features.py\n(Thick implementation module)"]:::module

    AGG["Shared Stage: Temporal Aggregation\n(Monthly bucketing)"]:::stage

    subgraph "Capabilities (Functions)"
      OVR["Overview Table\n(missingness, uniqueness,\nvolatility, correlation)"]:::capability
      PSI["Monthly Drift (PSI)\n+ threshold flags"]:::capability
      PCA["Temporal Movement (PCA 3D)\n+ distance metrics"]:::capability
      CP["Structural Breaks\n(Changepoint detection)"]:::capability
      IMP["Feature Importance Evolution\n(RF / XGBoost)"]:::capability
      HP["Trend Decomposition\n(HP filter: trend/seasonal/residual)"]:::capability
    end
  end
end

NB -->|"calls"| INIT
DF -->|"passed_to"| INIT
CFG -->|"passed_to"| INIT

INIT -->|"delegates"| FEAT
INIT -->|"exposes"| API_LIST

FEAT -->|"preprocesses"| AGG
AGG -->|"feeds"| OVR
AGG -->|"feeds"| PSI
AGG -->|"feeds"| PCA
AGG -->|"feeds"| CP
AGG -->|"feeds"| IMP
AGG -->|"feeds"| HP

%% =========================
%% Tier 3: Dependencies
%% =========================
subgraph "External Dependencies"
  PN["pandas / numpy\n(data handling + numeric ops)"]:::ext
  PL["plotly\n(interactive figures)"]:::ext
  IW["ipywidgets\n(notebook interactivity)"]:::ext
  SK["scikit-learn\n(PCA, preprocessing, RandomForest)"]:::ext
  XGB["xgboost\n(feature importance model)"]:::ext
  RUP["ruptures\n(PELT/Binseg/Dynp changepoints)"]:::ext
  SM["statsmodels\n(HP filter decomposition)"]:::ext
end

%% Core usage (common)
FEAT -->|"uses"| PN

%% Capability-specific dependency links
OVR -->|"uses"| PN
OVR -->|"optional_target_corr"| PN

PSI -->|"computes_with"| PN
PSI -->|"visualizes_with"| PL

PCA -->|"computes_with"| SK
PCA -->|"aggregates_with"| PN
PCA -->|"visualizes_with"| PL

CP -->|"detects_with"| RUP
CP -->|"visualizes_with"| PL

IMP -->|"trains_RF_with"| SK
IMP -->|"trains_XGB_with"| XGB
IMP -->|"visualizes_with"| PL

HP -->|"decomposes_with"| SM
HP -->|"visualizes_with"| PL

PL -->|"notebook_widgets"| IW

%% =========================
%% Outputs
%% =========================
subgraph "Outputs (What the User Sees)"
  OUT_TBL[/"Tables / DataFrames\n(overview + metrics)"/]:::output
  OUT_PSI[/"PSI Time Series Plot\n+ warnings/flags"/]:::output
  OUT_PCA[/"3D PCA Plot\n+ distance bars"/]:::output
  OUT_CP[/"Breakpoint Plot\n(changepoint markers)"/]:::output
  OUT_IMP[/"Importance Evolution Plot\n(monthly/rolling)"/]:::output
  OUT_HP[/"Trend / Seasonal / Residual Plot\n(HP filter)"/]:::output
end

OVR -.->|"returns"| OUT_TBL
PSI -.->|"returns"| OUT_PSI
PCA -.->|"returns"| OUT_PCA
CP -.->|"returns"| OUT_CP
IMP -.->|"returns"| OUT_IMP
HP -.->|"returns"| OUT_HP

OUT_TBL -.->|"consumed_in"| NB
OUT_PSI -.->|"rendered_in"| NB
OUT_PCA -.->|"rendered_in"| NB
OUT_CP -.->|"rendered_in"| NB
OUT_IMP -.->|"rendered_in"| NB
OUT_HP -.->|"rendered_in"| NB

%% =========================
%% Repo Metadata / Docs (context)
%% =========================
subgraph "Packaging & Documentation"
  PYPROJ["pyproject.toml\n(build + dependencies + versioning)"]:::meta
  RD["README.md\n(scope + API documentation)"]:::meta
end

PYPROJ -->|"declares_deps_for"| PKG
RD -->|"documents"| API_LIST
RD -->|"guides_usage"| DEMO

%% =========================
%% Click Events (from mapping)
%% =========================
click PKG "https://github.com/tergelitu/teda-v1/tree/main/teda/"
click INIT "https://github.com/tergelitu/teda-v1/blob/main/teda/__init__.py"
click FEAT "https://github.com/tergelitu/teda-v1/blob/main/teda/features.py"
click DEMO "https://github.com/tergelitu/teda-v1/blob/main/teda-demo.ipynb"
click PYPROJ "https://github.com/tergelitu/teda-v1/blob/main/pyproject.toml"
click RD "https://github.com/tergelitu/teda-v1/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef actor fill:#1f2937,stroke:#111827,color:#ffffff,stroke-width:1.5px
classDef consumer fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px
classDef input fill:#fff7ed,stroke:#fb923c,color:#7c2d12,stroke-width:1.5px
classDef pkg fill:#10b981,stroke:#047857,color:#06281d,stroke-width:1.5px
classDef module fill:#a7f3d0,stroke:#047857,color:#064e3b,stroke-width:1.5px
classDef api fill:#34d399,stroke:#047857,color:#053b2a,stroke-width:1.5px
classDef stage fill:#d1fae5,stroke:#059669,color:#064e3b,stroke-width:1.5px
classDef capability fill:#ecfeff,stroke:#06b6d4,color:#164e63,stroke-width:1.5px
classDef ext fill:#e0e7ff,stroke:#4f46e5,color:#1e1b4b,stroke-width:1.5px
classDef output fill:#fdf2f8,stroke:#db2777,color:#831843,stroke-width:1.5px
classDef meta fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1.2px
```
