# litefallen/keyboard_trainer architecture

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

- Interactive diagram: https://gitdiagram.com/litefallen/keyboard_trainer
- Repository: https://github.com/litefallen/keyboard_trainer

## Overview

##### Project type and purpose
- This is a full-stack web application written in Python using Flask.
- Purpose: provide users with a browser-based typing-test trainer, with user authentication and session-based results storage.

##### File structure
Top-level:
- main.py and draft.py – entry points
- application/ – Flask application package
- instance/application.sqlite – SQLite database
- requirements.txt – Python dependencies

application/ sub-structure:
- blueprints.py – blueprint definitions (routes grouping)
- database.py & models.py – ORM setup for user & test results
- key_listener.py – uses the external “keyboard” library to capture keystrokes
- words.py, words_sort.py – business logic for word selection & sorting
- static/ – CSS files under static/css
- templates/ – Jinja2 HTML templates for all pages

##### README for additional insights
- Confirms use of Flask, flask-login for auth.
- Uses the “keyboard” Python module for keystroke capture.
- Word lists imported from an external JSON/text dictionary.

##### Main components and relationships
a. Frontend (Client Browser)
– HTML templates (index, login, signup, typing_test, profile, main_page)
– CSS files (main.css, styles.css)
– Minimal or no custom JavaScript (server-side key capture via keyboard module)

b. Backend (Flask Application)
– Flask app instance (main.py initializes, application/blueprints.py registers routes)
– Auth subsystem (`flask-login`)
– Business logic modules:
- words.py & words_sort.py (word list loading, sorting algorithms)
- key_listener.py (real-time keystroke capture & timing)
– Data access layer:
- database.py (SQLAlchemy setup)
- models.py (User, TestResult models)
– Configuration:
- `.gitignore`, `requirements.txt`, `instance/` folder for secrets & SQLite file

c. Persistence
– SQLite database (`instance/application.sqlite`)

d. External services/libraries
– Python `keyboard` module for low-level key events
– External word-list repository (dwyl/english-words) pulled in as JSON/text files
– Flask-login for session management

##### Architectural patterns and design principles
- MVC (Model: models.py; View: Jinja2 templates; Controller: blueprint route functions)
- Modularization via Blueprints
- Separation of concerns:
- Auth logic isolated in `flask-login`
- Business logic in specialized modules (`words.py`, `key_listener.py`)
- Data layer in `database.py`/`models.py`

##### Final checklist
- Labels for technologies (Flask, SQLAlchemy, keyboard module)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Client Browser)"
        subgraph "HTML Templates"
            index["index.html"]:::frontend
            login["login.html"]:::frontend
            signup["signup.html"]:::frontend
            typing["typing_test.html"]:::frontend
            mainpage["main_page.html"]:::frontend
            profile["profile.html"]:::frontend
            base["base.html"]:::frontend
            header["header.html"]:::frontend
            footer["footer.html"]:::frontend
        end
        subgraph "CSS Stylesheets"
            maincss["main.css"]:::frontend
            styles["styles.css"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Flask App)"
        mainpy["main.py"]:::backend
        draftpy["draft.py"]:::backend
        blueprints["blueprints.py"]:::backend
        subgraph "Business Logic"
            words["words.py"]:::backend
            words_sort["words_sort.py"]:::backend
            keylistener["key_listener.py"]:::backend
        end
        subgraph "Data Access Layer"
            dbsetup["database.py"]:::backend
            models["models.py"]:::backend
        end
        requirements["requirements.txt"]:::backend
        gitignore[".gitignore"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence"
        sqlite["application.sqlite"]:::datastore
    end

    %% External Resources
    subgraph "External Resources"
        keyboardlib["keyboard module"]:::external
        loginlib["Flask-login"]:::external
        subgraph "Word List Files"
            finaljson["final_file.json"]:::external
            sortedjson["sorted_words.json"]:::external
            wordstxt["words.txt"]:::external
            dictjson["words_dictionary.json"]:::external
        end
    end

    %% Interactions
    index -->|"HTTP request/response"| blueprints
    login -->|"HTTP request/response"| blueprints
    signup -->|"HTTP request/response"| blueprints
    typing -->|"HTTP request/response"| blueprints
    mainpage -->|"HTTP request/response"| blueprints
    profile -->|"HTTP request/response"| blueprints
    base -->|"Template inheritance"| blueprints
    header -->|"Template inclusion"| blueprints
    footer -->|"Template inclusion"| blueprints

    maincss -->|"served static"| blueprints
    styles -->|"served static"| blueprints

    blueprints -->|"invokes"| words
    blueprints -->|"invokes"| words_sort
    blueprints -->|"invokes"| keylistener
    blueprints -->|"uses ORM"| dbsetup
    blueprints -->|"uses ORM"| models
    blueprints -->|"reads config"| requirements
    blueprints -->|"ignores files"| gitignore
    blueprints -->|"manages sessions"| loginlib

    words -->|"loads data from"| finaljson
    words_sort -->|"loads data from"| sortedjson
    words -->|"loads data from"| wordstxt
    words -->|"loads data from"| dictjson

    keylistener -->|"captures events from"| keyboardlib

    dbsetup -->|"reads/writes"| sqlite
    models -->|"reads/writes"| sqlite

    %% Click Events
    click index "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/index.html"
    click login "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/login.html"
    click signup "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/signup.html"
    click typing "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/typing_test.html"
    click mainpage "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/main_page.html"
    click profile "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/profile.html"
    click base "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/base.html"
    click header "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/header.html"
    click footer "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/templates/footer.html"
    click maincss "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/static/css/main.css"
    click styles "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/static/css/styles.css"
    click mainpy "https://github.com/litefallen/keyboard_trainer/blob/main_branch/main.py"
    click draftpy "https://github.com/litefallen/keyboard_trainer/blob/main_branch/draft.py"
    click blueprints "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/blueprints.py"
    click words "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/words.py"
    click words_sort "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/words_sort.py"
    click keylistener "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/key_listener.py"
    click dbsetup "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/database.py"
    click models "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/models.py"
    click requirements "https://github.com/litefallen/keyboard_trainer/blob/main_branch/requirements.txt"
    click gitignore "https://github.com/litefallen/keyboard_trainer/blob/main_branch/.gitignore"
    click sqlite "https://github.com/litefallen/keyboard_trainer/blob/main_branch/instance/application.sqlite"
    click finaljson "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/final_file.json"
    click sortedjson "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/sorted_words.json"
    click wordstxt "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/words.txt"
    click dictjson "https://github.com/litefallen/keyboard_trainer/blob/main_branch/application/words_dictionary.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
