# chuajeromepython/bert-spellchecker architecture

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

- Interactive diagram: https://gitdiagram.com/chuajeromepython/bert-spellchecker
- Repository: https://github.com/chuajeromepython/bert-spellchecker

## Overview

This repository is a local OCR-text correction tool: a terminal user submits text, SymSpell handles spelling and word-boundary errors, and BERT reranks candidates for contextual real-word errors before the result is displayed or saved. Separate scripts prepare domain text and fine-tune the BERT model; synthetic-case generation and accuracy scoring support evaluation. The main script’s excerpt omits some entry-point details, so those workflow links rely on the README; unsampled implementation details are not inferred.

Main entry points: [`BERT-spellchecker.py`](https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py) (Correction CLI), [`accuracy_tests/run_accuracy_tests.py`](https://github.com/chuajeromepython/bert-spellchecker/blob/main/accuracy_tests/run_accuracy_tests.py) (Pipeline accuracy scoring), [`prepare_finetune_data.py`](https://github.com/chuajeromepython/bert-spellchecker/blob/main/prepare_finetune_data.py) (Training data preparation), [`finetune_data/train.txt`](https://github.com/chuajeromepython/bert-spellchecker/blob/main/finetune_data/train.txt) (Train and validation text)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_correction["Correction runtime"]
  node_pipeline["Correction CLI"]
  node_symspell["SymSpell correction"]
  node_reranking["BERT reranking"]
  node_model_files["Fine-tuned model"]
end

subgraph group_model["Model preparation"]
  node_raw_text["Domain text"]
  node_data_prep["Training data preparation"]
  node_train_val["Train and validation text<br/>[train.txt]"]
  node_finetuner["BERT fine-tuning<br/>[finetune_bert.py]"]
end

subgraph group_evaluation["Evaluation tools"]
  node_synthetic["Synthetic case generator"]
  node_cases["Accuracy cases<br/>[test_cases.json]"]
  node_accuracy["Pipeline accuracy scoring"]
  node_results["Score history"]
end

node_user(("Terminal user"))

node_user -->|"enters text"| node_pipeline
node_pipeline -->|"runs stage one"| node_symspell
node_pipeline -->|"runs stage two"| node_reranking
node_pipeline -->|"prints or saves"| node_user
node_symspell -->|"passes corrected text"| node_reranking
node_reranking -->|"loads model"| node_model_files
node_raw_text -->|"reads text"| node_data_prep
node_data_prep -->|"writes splits"| node_train_val
node_train_val -->|"loads splits"| node_finetuner
node_finetuner -->|"saves model"| node_model_files
node_synthetic -.->|"generates cases"| node_cases
node_accuracy -->|"loads cases"| node_cases
node_accuracy -->|"loads and calls"| node_pipeline
node_accuracy -->|"saves scores"| node_results

click node_pipeline "https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py"
click node_symspell "https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py"
click node_reranking "https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py"
click node_model_files "https://github.com/chuajeromepython/bert-spellchecker/tree/main/finetuned-bert-spellchecker"
click node_raw_text "https://github.com/chuajeromepython/bert-spellchecker/tree/main/finetune_data/raw"
click node_data_prep "https://github.com/chuajeromepython/bert-spellchecker/blob/main/prepare_finetune_data.py"
click node_train_val "https://github.com/chuajeromepython/bert-spellchecker/blob/main/finetune_data/train.txt"
click node_finetuner "https://github.com/chuajeromepython/bert-spellchecker/blob/main/finetune_bert.py"
click node_synthetic "https://github.com/chuajeromepython/bert-spellchecker/blob/main/gen_synthetic_cases.py"
click node_cases "https://github.com/chuajeromepython/bert-spellchecker/blob/main/accuracy_tests/test_cases.json"
click node_accuracy "https://github.com/chuajeromepython/bert-spellchecker/blob/main/accuracy_tests/run_accuracy_tests.py"
click node_results "https://github.com/chuajeromepython/bert-spellchecker/tree/main/accuracy_tests/results"

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_pipeline,node_symspell,node_reranking,node_model_files,node_user toneBlue
class node_raw_text,node_data_prep,node_train_val,node_finetuner toneAmber
class node_synthetic,node_cases,node_accuracy,node_results toneMint
```

## Components

### Correction runtime

- [Correction CLI](https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py): `BERT-spellchecker.py`
- [SymSpell correction](https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py): `BERT-spellchecker.py`
- [BERT reranking](https://github.com/chuajeromepython/bert-spellchecker/blob/main/BERT-spellchecker.py): `BERT-spellchecker.py`
- [Fine-tuned model](https://github.com/chuajeromepython/bert-spellchecker/tree/main/finetuned-bert-spellchecker): `finetuned-bert-spellchecker`

### Model preparation

- [Domain text](https://github.com/chuajeromepython/bert-spellchecker/tree/main/finetune_data/raw): `finetune_data/raw`
- [Training data preparation](https://github.com/chuajeromepython/bert-spellchecker/blob/main/prepare_finetune_data.py): `prepare_finetune_data.py`
- [Train and validation text](https://github.com/chuajeromepython/bert-spellchecker/blob/main/finetune_data/train.txt): `finetune_data/train.txt`
- [BERT fine-tuning](https://github.com/chuajeromepython/bert-spellchecker/blob/main/finetune_bert.py): `finetune_bert.py`

### Evaluation tools

- [Synthetic case generator](https://github.com/chuajeromepython/bert-spellchecker/blob/main/gen_synthetic_cases.py): `gen_synthetic_cases.py`
- [Accuracy cases](https://github.com/chuajeromepython/bert-spellchecker/blob/main/accuracy_tests/test_cases.json): `accuracy_tests/test_cases.json`
- [Pipeline accuracy scoring](https://github.com/chuajeromepython/bert-spellchecker/blob/main/accuracy_tests/run_accuracy_tests.py): `accuracy_tests/run_accuracy_tests.py`
- [Score history](https://github.com/chuajeromepython/bert-spellchecker/tree/main/accuracy_tests/results): `accuracy_tests/results`

### Other components

- **Terminal user**

## Connections

- Terminal user → Correction CLI: enters text (evidence: `README.md`)
- Correction CLI → SymSpell correction: runs stage one (evidence: `README.md`)
- Correction CLI → BERT reranking: runs stage two (evidence: `README.md`)
- Correction CLI → Terminal user: prints or saves (evidence: `README.md`)
- SymSpell correction → BERT reranking: passes corrected text (evidence: `BERT-spellchecker.py`)
- BERT reranking → Fine-tuned model: loads model (evidence: `BERT-spellchecker.py`)
- Domain text → Training data preparation: reads text (evidence: `prepare_finetune_data.py`)
- Training data preparation → Train and validation text: writes splits (evidence: `prepare_finetune_data.py`)
- Train and validation text → BERT fine-tuning: loads splits (evidence: `finetune_bert.py`)
- BERT fine-tuning → Fine-tuned model: saves model (evidence: `finetune_bert.py`)
- Synthetic case generator → Accuracy cases: generates cases
- Pipeline accuracy scoring → Accuracy cases: loads cases (evidence: `accuracy_tests/run_accuracy_tests.py`)
- Pipeline accuracy scoring → Correction CLI: loads and calls (evidence: `accuracy_tests/run_accuracy_tests.py`)
- Pipeline accuracy scoring → Score history: saves scores (evidence: `accuracy_tests/run_accuracy_tests.py`)