# codebreaker518/ia1114_rna_greekletters architecture

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

- Interactive diagram: https://gitdiagram.com/codebreaker518/ia1114_rna_greekletters
- Repository: https://github.com/codebreaker518/ia1114_rna_greekletters

## Overview

The project is a machine learning backend designed to recognize handwritten, lowercase Greek letters using a custom-built Multilayer Perceptron (MLP). It leverages image processing (via OpenCV) and feature extraction (using HOG) before passing data through the neural network built from scratch with NumPy. The backend exposes an API (implemented with FastAPI) for real-time predictions and provides a command-line interface for training and testing the model.

##### Main Components
- Data Storage and Dataset:
- The directory "Greek_Letters/" holds subdirectories for each letter (alpha, beta, chi, etc.) which form the image dataset for training.
- Image Preprocessing Pipeline:
- Component that handles image loading, processing with OpenCV, and HOG feature extraction.
- Neural Network (MLP) Module:
- Custom neural network implementation using NumPy.
- Consists of an Input Layer (3780 HOG features), one Hidden Layer (392 neurons), and an Output Layer (24 Greek letter classes) using tanh and softmax activation functions.
- Implements backpropagation for training.
- API Server:
- Built using FastAPI, this component exposes endpoints:
- GET /: for health checking.
- POST /predict: to obtain Greek letter predictions from uploaded .png images.
- Model Management & CLI:
- Allows switching between Training Mode (loading, preprocessing, training, evaluating, and saving the model) and Testing Mode (using a saved model for predictions).
- Persistence:
- The trained model is saved to a pickle file (e.g., greek_letters_model.pkl) for later inference.

##### Relationships and Data Flow
- Data Flow begins from the Image Dataset (Greek_Letters) which feeds into the Image Processing component.
- Processed features (HOG features) are then fed into the Neural Network module.
- Training and Testing pipelines interact with the Neural Network to either update model weights or predict.
- The API Server serves as the gateway for external requests: When an image is received through POST /predict, the API calls the preprocessing pipeline before passing features to the neural network for prediction.
- The command-line interface offers a control layer for training, evaluation, and starting the API server.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Distinct components for preprocessing, model training, and API handling.
- Pipeline Architecture: Image input flows sequentially through preprocessing, feature extraction, and neural network prediction.
- Extensibility: The clear separation of training and inference pipelines coupled with exposed API endpoints.

##### Detail Level
- Be as detailed as possible while capturing all essential components.
- Technical details noted in the README such as the architecture of the neural network and the primary libraries (NumPy for neural network implementation, OpenCV for image processing, FastAPI for the server, Matplotlib/Seaborn for visualization).
- Don’t shy away from diagramming separate components for model persistence (saving/loading the python pickle file of the trained model).

- Modules are labeled, and data flow pathways are explicitly drawn.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        A["Dataset Loader (Greek_Letters)"]:::data
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        B["Image Preprocessing & HOG Extraction"]:::processing
    end

    %% MLP Module
    subgraph "MLP Neural Network"
        C["Custom MLP (Input: 3780, Hidden: 392 (tanh), Output: 24 (softmax), Backprop)"]:::ml
    end

    %% Control & Persistence
    subgraph "Control & Persistence"
        D["Model Management & CLI (Training/Testing)"]:::interface
        E["Model Persistence (greek_letters_model.pkl)"]:::persistence
    end

    %% Interface Layer
    subgraph "Interface Layer"
        F["FastAPI Server (GET /, POST /predict)"]:::interface
    end

    %% Data Flow
    A -->|"loads images"| B
    B -->|"extracts features"| C
    C -->|"triggers training"| D
    D -->|"saves model"| E

    %% API Interaction Flow
    F -->|"invokes preprocessing"| B
    C -->|"returns prediction"| F

    %% Classes for styling
    classDef data fill:#8ecae6,stroke:#219ebc,stroke-width:2px;
    classDef processing fill:#ffb703,stroke:#fb8500,stroke-width:2px;
    classDef ml fill:#219ebc,stroke:#023047,stroke-width:2px;
    classDef interface fill:#ffddd2,stroke:#d62828,stroke-width:2px;
    classDef persistence fill:#d0f4de,stroke:#57a773,stroke-width:2px;

    %% Click Events
    click A "https://github.com/codebreaker518/ia1114_rna_greekletters/tree/main/Greek_Letters/"
    click B "https://github.com/codebreaker518/ia1114_rna_greekletters/blob/main/main.py"
    click C "https://github.com/codebreaker518/ia1114_rna_greekletters/blob/main/main.py"
    click D "https://github.com/codebreaker518/ia1114_rna_greekletters/blob/main/main.py"
    click F "https://github.com/codebreaker518/ia1114_rna_greekletters/blob/main/main.py"
```
