How dyslexiaworkin/dyslexiaml works
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)