# coderdotexe/hbpa architecture

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

- Interactive diagram: https://gitdiagram.com/coderdotexe/hbpa
- Repository: https://github.com/coderdotexe/hbpa

## Overview

##### Project Type and Purpose
- This is a Python-based machine learning pipeline for handwriting-based psychological assessment.
- The system ingests scanned handwriting images, applies preprocessing, extracts features, labels data, trains/predicts via ML models (SVM by default), and outputs trait predictions.

##### Main Architectural Components
a. Data Layer
- Source: IAM Handwriting Database (external).
- Local storage:
- images/ (processed PNGs)
- data/samples/ (raw images, per README)
- feature_list, raw_feature_list, label_list (flat files storing intermediate data).
b. Ingestion & Preprocessing
- Scripts: extract.py, extract_v3.py, extract_routine.py
- Tasks: resolution enhancement, noise reduction, grayscale conversion, contour detection, warp affinities, projections
c. Feature Extraction
- Scripts: ExtractFeature.py, feature_routine.py
- Outputs: baseline, margins, letter size, spacing metrics, pen pressure, slant angle
d. Labeling
- Scripts: label_routine.py, categorize.py
- Creates mappings from features to psychological traits (eight traits)
e. Model Training & Prediction
- Scripts: train_predict.py, train_predict_v3.py
- Libraries: scikit-learn (SVM), numpy, pandas
- Produces terminal output with predicted trait scores
f. Reporting/Output
- Terminal prints
- (Future scope: UI layer, possibly web or desktop)

##### Interactions and Data Flow
- External Dataset → Data Layer (raw images)
↓
- Ingestion & Preprocessing → cleans and standardizes images → images/
↓
- Feature Extraction → reads processed images, writes feature_list/raw_feature_list
↓
- Labeling → reads features, applies label_list, writes training labels
↓
- Model Training & Prediction → reads features + labels, fits/predicts → prints results
↓
- Output → Terminal (and logs if extended)

##### Architectural Patterns & Principles
- Pipeline Pattern: clear sequential stages
- Modular Separation: each stage in its own script/routine
- Single Responsibility: one script per processing step
- File-based messaging: flat files as intermediate queues
- Extensibility: future CNN integration, UI layer

##### Technologies & Libraries
- Python 3.x, OpenCV (cv2), scikit-learn (SVM), numpy, pandas
- Flat files (lists) for simple persistence
- Parent README mentions future use of CNNs

##### Detail Level
- .py scripts as distinct processing nodes.
- Intermediate artifact files as data stores.
- Do not merge stages—better to show more granular steps.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dataset
    External["IAM Handwriting Database"]:::external

    %% Data Layer
    subgraph "Data Layer"
        RawImages["data/samples/ (Raw Images)"]:::dataStore
        ProcessedImages["images/ (Processed PNGs)"]:::dataStore
        FeatureList["feature_list"]:::dataStore
        RawFeatureList["raw_feature_list"]:::dataStore
        LabelList["label_list"]:::dataStore
    end

    %% Ingestion & Preprocessing
    subgraph "Ingestion & Preprocessing"
        extractPy["extract.py"]:::processing
        extractV3["extract_v3.py"]:::processing
        extractRoutine["extract_routine.py"]:::processing
    end

    %% Feature Extraction
    subgraph "Feature Extraction"
        ExtractFeature["ExtractFeature.py"]:::feature
        featureRoutine["feature_routine.py"]:::feature
    end

    %% Labeling
    subgraph "Labeling"
        labelRoutine["label_routine.py"]:::processing
        categorize["categorize.py"]:::processing
    end

    %% Model Training & Prediction
    subgraph "Model Training & Prediction"
        trainPredict["train_predict.py"]:::ml
        trainPredictV3["train_predict_v3.py"]:::ml
    end

    %% Output
    Terminal["Terminal Output"]:::output

    %% Flow
    External -->|provides raw data| RawImages
    RawImages --> extractPy
    RawImages --> extractV3
    RawImages --> extractRoutine
    extractPy --> ProcessedImages
    extractV3 --> ProcessedImages
    extractRoutine --> ProcessedImages

    ProcessedImages --> ExtractFeature
    ExtractFeature --> RawFeatureList
    RawFeatureList --> featureRoutine
    featureRoutine --> FeatureList

    FeatureList --> labelRoutine
    labelRoutine --> categorize
    categorize --> LabelList

    FeatureList --> trainPredict
    LabelList --> trainPredict
    trainPredict --> Terminal

    FeatureList --> trainPredictV3
    LabelList --> trainPredictV3
    trainPredictV3 --> Terminal

    %% Click Events
    click RawImages "https://github.com/coderdotexe/hbpa/tree/main/data/samples/"
    click ProcessedImages "https://github.com/coderdotexe/hbpa/tree/main/images/"
    click FeatureList "https://github.com/coderdotexe/hbpa/tree/main/feature_list"
    click RawFeatureList "https://github.com/coderdotexe/hbpa/tree/main/raw_feature_list"
    click LabelList "https://github.com/coderdotexe/hbpa/tree/main/label_list"
    click extractPy "https://github.com/coderdotexe/hbpa/blob/main/extract.py"
    click extractV3 "https://github.com/coderdotexe/hbpa/blob/main/extract_v3.py"
    click extractRoutine "https://github.com/coderdotexe/hbpa/blob/main/extract_routine.py"
    click ExtractFeature "https://github.com/coderdotexe/hbpa/blob/main/ExtractFeature.py"
    click featureRoutine "https://github.com/coderdotexe/hbpa/blob/main/feature_routine.py"
    click labelRoutine "https://github.com/coderdotexe/hbpa/blob/main/label_routine.py"
    click categorize "https://github.com/coderdotexe/hbpa/blob/main/categorize.py"
    click trainPredict "https://github.com/coderdotexe/hbpa/blob/main/train_predict.py"
    click trainPredictV3 "https://github.com/coderdotexe/hbpa/blob/main/train_predict_v3.py"

    %% Styles
    classDef dataStore fill:#ADD8E6,stroke:#000
    classDef processing fill:#FFA500,stroke:#000
    classDef feature fill:#90EE90,stroke:#000
    classDef ml fill:#DDA0DD,stroke:#000
    classDef output fill:#D3D3D3,stroke:#000
    classDef external fill:#FFE4C4,stroke:#000
```
