# dyslexiaworkin/dyslexiaml architecture

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

- Interactive diagram: https://gitdiagram.com/dyslexiaworkin/dyslexiaml
- Repository: https://github.com/dyslexiaworkin/dyslexiaml

## Overview

##### Project type and purpose
- DyslexiaML is a full-stack web application whose core purpose is to detect signs of dyslexia using a machine-learning model.
- It includes both a web UI (pages/, app.py, style.css) and an ML inference component (model.py, transform_predict.joblib), plus a small SQLite database (data.db) for user/session data or quiz results.

##### File structure
- Top-level files:
- app.py – main application entry point and router/controller
- model.py / DyslexiaML.py – model loading, prediction logic
- SessionState.py – manages per-session data in memory
- data.db – SQLite DB storing user data or quiz responses
- transform_predict.joblib – serialized trained model
- Pipfile – dependency management
- pages/ directory (UI endpoints):
- home.py, login.py, quiz.py, survey.py – UI page implementations
- config.py – configuration settings, DB connection code
- fetch.py – helper for retrieving data (from DB or model)
- Jupyter notebooks and .py scripts under the root are used for dataset labeling and model training; these belong in a “development/pipeline” sub-system.

##### Key insights from README
- Simple one-sentence project description confirms ML-based dyslexia detection. No external services documented, so everything is self-hosted.

##### Main components of the system
a. Web Frontend (UI Layer)
– Browser/client interacts via HTTP.
– style.css for styling.
– pages/home.py, pages/login.py, pages/quiz.py, pages/survey.py render views and collect user input.
b. Backend Application (Controller/Router)
– app.py orchestrates routing to the pages and wires in SessionState.
c. ML Inference Service
– model.py (and DyslexiaML.py) loads transform_predict.joblib, exposes a predict(input_data) interface.
d. Data Storage
– SQLite database (data.db) accessed via pages/config.py and fetch.py.
e. Development & Training Pipeline (Auxiliary)
– Jupyter notebooks (Model-implementation.ipynb, etc.) and DyslexiaML.py script – used offline to train models and export joblib.

##### Relationships and data flow
1. User → Web Browser: submits login/quiz/survey via UI pages
2. Browser → app.py: HTTP requests routed by the main application
3. app.py → SessionState: manages session data in memory per user
4. app.py → Database (data.db): reads/writes user or quiz data via config.py + fetch.py
5. app.py → ML Inference (model.py): passes preprocessed user response data, receives dyslexia risk prediction
6. Prediction → app.py → Browser: results displayed on the UI
7. Training Notebooks → Offline: produce transform_predict.joblib stored for inference

##### Architectural patterns and design principles
- MVC-like separation: pages/ = Views, app.py = Controller, config.py + data.db = Model (data).
- Single codebase for frontend/back end (no separate microservices).
- Use of dependency management (Pipfile) for reproducible environments.
- Lightweight persistence via SQLite suited for small footprint.

- Optional: annotate data formats (CSV, JSON, joblib)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Web Browser (User)"]:::client

    %% UI Pages
    subgraph "UI Pages" 
        Home["home.py"]:::ui
        Login["login.py"]:::ui
        Quiz["quiz.py"]:::ui
        Survey["survey.py"]:::ui
        Style["style.css"]:::ui
    end

    %% Application Layer
    Controller["app.py (Router/Controller)"]:::app
    Session["SessionState Service"]:::app

    %% Data Layer
    subgraph "Data Access"
        Config["pages/config.py"]:::db
        Fetch["pages/fetch.py"]:::db
        DB[(data.db)]:::db
    end

    %% ML Layer
    subgraph "ML Inference Service"
        ModelCode["model.py"]:::ml
        Transform["transform_predict.joblib"]:::ml
        DML["DyslexiaML.py"]:::ml
    end

    %% Development Pipeline
    subgraph "Development & Training Pipeline"
        NB1["Model-implementation.ipynb"]:::dev
        NB2["Model-implementationRobust.ipynb"]:::dev
        NB3["labellingdata.ipynb"]:::dev
        NB4["Database.ipynb"]:::dev
        Script["DyslexiaML.py"]:::dev
    end

    %% Data Flow
    Browser -->|"Submit login/quiz/survey"| Home
    Browser --> Home
    Browser --> Login
    Browser --> Quiz
    Browser --> Survey
    Home -->|"HTTP Request"| Controller
    Login -->|"HTTP Request"| Controller
    Quiz -->|"HTTP Request"| Controller
    Survey -->|"HTTP Request"| Controller
    Style --- Home
    Style --- Login
    Style --- Quiz
    Style --- Survey

    Controller -->|"manage session"| Session
    Controller -->|"read/write data"| Config
    Config --> Fetch
    Fetch --> DB
    Controller -->|"predict(input_data)"| ModelCode
    ModelCode --> Transform
    ModelCode --> DML
    ModelCode -->|"loads model"| Transform
    ModelCode -->|"uses logic"| DML
    ModelCode --> Controller

    %% Development flow
    NB1 --> Script
    NB2 --> Script
    NB3 --> Script
    NB4 --> Script
    Script --> Transform

    %% Click Events
    click Home "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/home.py"
    click Login "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/login.py"
    click Quiz "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/quiz.py"
    click Survey "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/survey.py"
    click Style "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/style.css"
    click Controller "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/app.py"
    click Session "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/SessionState.py"
    click Config "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/config.py"
    click Fetch "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/pages/fetch.py"
    click DB "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/data.db"
    click ModelCode "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/model.py"
    click Transform "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/transform_predict.joblib"
    click DML "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/DyslexiaML.py"
    click NB1 "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/Model-implementation.ipynb"
    click NB2 "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/Model-implementationRobust.ipynb"
    click NB3 "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/labellingdata.ipynb"
    click NB4 "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/Database.ipynb"
    click Script "https://github.com/dyslexiaworkin/dyslexiaml/blob/master/DyslexiaML.py"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#0275d8,color:#000
    classDef ui fill:#CFE2F3,stroke:#2a76d2,color:#000
    classDef app fill:#D4EDDA,stroke:#28a745,color:#000
    classDef db fill:#FFF3CD,stroke:#FFC107,color:#000
    classDef ml fill:#E2D8F7,stroke:#6f42c1,color:#000
    classDef dev fill:#E2E3E5,stroke:#6c757d,color:#000
```
