# sujith0613/scribogenie architecture

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

- Interactive diagram: https://gitdiagram.com/sujith0613/scribogenie
- Repository: https://github.com/sujith0613/scribogenie

## Overview

1. **What this repository is**
   - ScriboGenie is a **local handwriting-recognition desktop application** with a separate **model-training notebook**.
   - The repo is not a multi-service system; the runtime path is centered on **one Python GUI app** that loads a pretrained CNN model.

2. **Primary runtime boundary**
   - `app9.py` is the main application entry point.
   - It appears to own the full interactive loop: **ink capture, drawing tools, preprocessing, recognition, correction, and displaying results**.
   - The app is intended to run offline, with no network dependency.

3. **User interaction layer**
   - The UI is a **Tkinter-based handwriting canvas** with drawing/erasing and editing controls such as undo/redo and brush settings.
   - This is the boundary where handwritten input becomes application data.
   - Input is described as coming from a **Wacom pad / pen input device**, though the repository itself is a general desktop Python app.

4. **Image capture and segmentation pipeline**
   - The app takes raw stroke/canvas data and converts it into image-like inputs for recognition.
   - The README indicates support for **live prediction** and **automatic segmentation / word grouping**, so there is a processing stage between drawing and prediction.
   - This stage likely normalizes handwritten input into model-ready character images.

5. **Recognition subsystem**
   - The core ML artifact is `myCnn.h5`, a **TensorFlow/Keras CNN model**.
   - It is trained on **EMNIST ByClass** with **62 classes** covering digits, uppercase letters, and lowercase letters.
   - This is the main inference boundary: the application sends processed glyphs to the model and receives character predictions.

6. **Preprocessing and model assumptions**
   - The model pipeline includes **orientation correction, normalization, and resizing**.
   - These steps are essential because the recognition model expects a consistent input format regardless of the user’s handwriting scale or alignment.
   - The repo also mentions optional augmentation during training, which affects model robustness but not the runtime UI architecture.

7. **Dyslexia-aware correction layer**
   - Above raw recognition sits a correction subsystem described as handling **common inversion and mirroring errors**.
   - The README also references a **spellchecker**, suggesting that after character recognition the app may refine results into more plausible text.
   - Architecturally, this is a separate semantic layer: it transforms model output into more user-friendly text.

8. **Feedback/output layer**
   - The system is designed to present recognized and corrected text in a **side panel** and to support **visual, auditory, and tactile feedback** conceptually.
   - In the repo, the visible runtime output is the GUI feedback path; the multisensory aspects are part of the product design described in the README.
   - This layer closes the loop from recognition back to the learner.

9. **Training and experimentation path**
   - `CNN_Training.ipynb` is the offline training workflow.
   - It uses the ML and visualization stack named in the README: **TensorFlow, Albumentations, Matplotlib, OpenCV, Pillow**.
   - This path produces the deployable model artifact `myCnn.h5`, which is then consumed by the GUI app.

10. **Repository-level artifact structure**
   - `myCnn.h5` is the deployed inference model.
   - `CNN_Training.ipynb` is the model-development notebook.
   - `app9.py` is the operational application layer.
   - The repo is therefore organized around a simple split: **training artifact generation** versus **interactive inference application**.

11. **External dependencies and constraints**
   - The architecture depends on the local Python ML/runtime stack rather than cloud services.
   - Material dependencies include **TensorFlow/Keras for inference**, **Tkinter for UI**, and **OpenCV/Pillow for image handling**.
   - Hardware context matters: the system is designed for **pen-tablet handwriting capture**, likely with embedded or low-power deployment in mind.

12. **What an architecture diagram should show**
   - A good diagram would have three main blocks: **input/UI**, **ML recognition + correction**, and **output/feedback**.
   - A separate offline block should show **training notebook → trained CNN model file**.
   - The model file sits at the boundary between offline training and runtime inference, and the app consumes it directly.

Main entry points: [`app9.py`](https://github.com/sujith0613/scribogenie/blob/main/app9.py) (ScriboGenie), [`myCnn.h5`](https://github.com/sujith0613/scribogenie/blob/main/myCnn.h5) (CNN model), [`CNN_Training.ipynb`](https://github.com/sujith0613/scribogenie/blob/main/CNN_Training.ipynb) (Training notebook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime app"]
  node_app["ScriboGenie<br/>desktop app<br/>[app9.py]"]
  node_canvas["Ink canvas<br/>ui input<br/>[app9.py]"]
  node_preprocess["Preprocess<br/>image prep<br/>[app9.py]"]
  node_segment["Segmentation<br/>word grouping<br/>[app9.py]"]
  node_model[("CNN model<br/>keras model<br/>[myCnn.h5]")]
  node_correct{{"Correction<br/>postprocess<br/>[app9.py]"}}
  node_output["Results panel<br/>feedback UI<br/>[app9.py]"]
end

subgraph group_training["Training"]
  node_train["Training notebook<br/>ml workflow<br/>[CNN_Training.ipynb]"]
end

node_canvas -->|"strokes"| node_segment
node_segment -->|"glyphs"| node_preprocess
node_preprocess -->|"inference"| node_model
node_model -->|"predictions"| node_correct
node_correct -->|"text"| node_output
node_app -->|"controls"| node_canvas
node_app -->|"pipeline"| node_preprocess
node_app -->|"logic"| node_correct
node_app -->|"display"| node_output
node_train -.->|"produces"| node_model

click node_app "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_canvas "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_preprocess "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_segment "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_model "https://github.com/sujith0613/scribogenie/blob/main/myCnn.h5"
click node_correct "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_output "https://github.com/sujith0613/scribogenie/blob/main/app9.py"
click node_train "https://github.com/sujith0613/scribogenie/blob/main/CNN_Training.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_canvas,node_preprocess,node_segment,node_model,node_correct,node_output toneBlue
class node_train toneAmber
```

## Components

### Runtime app

Interactive handwriting recognition flow used during normal desktop use.

- [ScriboGenie](https://github.com/sujith0613/scribogenie/blob/main/app9.py): desktop app · Main Tkinter application entry point handling handwriting capture, editing, preprocessing, recognition, correction, and result display. · `app9.py`
- [Ink canvas](https://github.com/sujith0613/scribogenie/blob/main/app9.py): ui input · Drawing surface and editing controls for pen input, erasing, undo/redo, and brush settings. · `app9.py`
- [Preprocess](https://github.com/sujith0613/scribogenie/blob/main/app9.py): image prep · Normalizes handwriting strokes into model-ready glyph images through resizing, alignment, and orientation correction. · `app9.py`
- [Segmentation](https://github.com/sujith0613/scribogenie/blob/main/app9.py): word grouping · Groups raw strokes or canvas content into character or word units for live prediction. · `app9.py`
- [CNN model](https://github.com/sujith0613/scribogenie/blob/main/myCnn.h5): keras model · Deployed TensorFlow/Keras classifier trained on EMNIST ByClass for character recognition. · `myCnn.h5`
- [Correction](https://github.com/sujith0613/scribogenie/blob/main/app9.py): postprocess · Applies dyslexia-aware fixes such as inversion or mirroring correction and plausibility refinement. · `app9.py`
- [Results panel](https://github.com/sujith0613/scribogenie/blob/main/app9.py): feedback UI · Displays recognized and corrected text back to the user and closes the interaction loop. · `app9.py`

### Training

Offline model development and artifact creation.

- [Training notebook](https://github.com/sujith0613/scribogenie/blob/main/CNN_Training.ipynb): ml workflow · Offline experimentation and training workflow for building the handwriting model. · `CNN_Training.ipynb`

## Connections

- Ink canvas → Segmentation: strokes · Captured pen input is grouped into characters or words.
- Segmentation → Preprocess: glyphs · Segments are normalized into model-ready images.
- Preprocess → CNN model: inference · Prepared handwriting images are classified by the CNN.
- CNN model → Correction: predictions · Raw character predictions are refined for likely inversions and errors.
- Correction → Results panel: text · Corrected recognition results are rendered in the GUI.
- ScriboGenie → Ink canvas: controls · The main application owns drawing, editing, and UI event handling.
- ScriboGenie → Preprocess: pipeline · The app orchestrates preprocessing before recognition.
- ScriboGenie → Correction: logic · The app applies correction and spellchecking logic.
- ScriboGenie → Results panel: display · The app presents recognition results to the user.
- Training notebook → CNN model: produces · The notebook trains and exports the deployable CNN artifact.