How piyushb03/mind-sphere works
1. What this repo is
MindSphere is a Flask-based mental health screening web app with two major concerns: a browser-facing assessment experience and an ML inference layer that returns both a risk prediction and an explanation of why that prediction was made.
2. Core runtime boundary
The serving application is app.py, which is the central web entry point. It likely owns routing, session/auth handling, form submission, history views, and orchestration between the UI and the ML helper layer. The app is packaged for deployment with a Procfile, which suggests a process-based host such as Heroku or a similar PaaS.
3. Web/UI layer
The user interface is entirely server-rendered HTML under templates/, with shared layout in base.html and page-specific screens like index, login, register, dashboard, result, history, and legal. Styling lives in static/css/style.css. This is a classic Flask template/static split rather than a SPA architecture.
4. Assessment flow
The main user journey is: landing page → authentication or direct access depending on app rules → dashboard assessment form → prediction result page. The dashboard collects lifestyle, demographic, and psychological inputs, which are mapped to the model’s expected feature schema before inference.
5. ML inference subsystem
model_utils.py is the ML service layer. Based on the README and artifacts, it is responsible for loading the serialized model, applying the saved encoders, preparing inputs, and producing predictions. The serving model is an XGBoost classifier stored in models/final_model.pkl, with categorical preprocessing in models/encoders.pkl.
6. Explainability subsystem
A key architectural feature is SHAP-based explainability. The prediction path does not stop at a class or score; it also computes feature contributions for the individual assessment and exposes them on the result page. That makes the inference output a pair: risk estimate plus explanation payload.
7. Persistence and user state
The repository indicates user/session persistence through Flask-SQLAlchemy and Flask-Login, with a SQLite database expected in instance/site.db per the README. The history.html page suggests past assessments are stored and later retrieved per user, creating a user-specific assessment ledger rather than a stateless one-shot prediction flow.
8. Authentication boundary
Authentication is a separate subsystem from prediction. The repo supports hashed local credentials plus Google OAuth 2.0 integration via Authlib. This means the app has two identity paths: database-backed login/register and federated sign-in, both feeding into the same authenticated dashboard/history experience.
9. Report generation/output
The README describes PDF report generation from assessment results. Architecturally, this is an output/export path fed by the prediction and explanation data, likely producing a downloadable or printable summary for the current assessment and possibly stored history entries.
10. Offline training vs online serving
The notebook/ directory is clearly the offline data science workspace: EDA, training, dataset CSV, and alternate serialized artifacts live there. This is separated from the serving path, which uses the committed models/ pickles. In diagram terms, training is an upstream, non-user-facing pipeline that produces deployable model assets consumed by the Flask app.
11. Data and artifact boundary
The runtime app depends on a small set of immutable ML assets: model and encoder pickle files. That keeps inference deterministic and avoids retraining in production. The notebooks and survey.csv are analysis/training inputs, not part of the live request path.
12. External integrations
The architecture includes environment-driven integration points for Google OAuth and likely a form or contact endpoint via Formspree, as indicated in the README. These are configuration-time dependencies rather than internal modules, so they sit at the edge of the system and should be shown outside the Flask core.
13. Practical diagram shape
A useful architecture diagram would show four layers: browser/UI templates and CSS; Flask app/controller layer; ML + explainability services loading pickled artifacts; and persistence/auth services backed by SQLite plus OAuth. The offline notebook/training workspace should be shown separately as a build-time pipeline that produces the runtime model files.
Main entry points: app.py app.py · model_utils.py model_utils.py · train_model.ipynb Train model · dashboard.html Dashboard
Components 24
Web UI
Server-rendered pages and shared styling for the assessment experience.
- Base layout · Common page shell used by the rendered views.
templates/base.html - Landing page · Entry screen for the app and first user touchpoint.
templates/index.html - Login page · Local sign-in screen for authenticated access.
templates/login.html - Register page · Account creation screen for local credentials.
templates/register.html - Dashboard · Assessment form where user inputs are collected.
templates/dashboard.html - Result page · Prediction output and explanation view.
templates/result.html - History page · Past assessments and prior results for a user.
templates/history.html - Legal page · Static legal and policy content.
templates/legal.html - Stylesheet · Shared presentation layer for the server-rendered UI.
static/css/style.css
Flask App
Request handling, orchestration, and user-facing flows.
ML Serving
Model loading, preprocessing, prediction, and explainability.
- model_utils.py · Loads model assets, prepares features, and produces predictions plus explanations.
model_utils.py - XGBoost model · Committed production model artifact used at inference time.
models/final_model.pkl - Encoders · Saved categorical encoders used to align form inputs with model features.
models/encoders.pkl - SHAP explain · Feature attribution layer that turns predictions into per-input explanations.
Training Workspace
Offline notebook environment and generated model assets.
- Notebooks · Offline EDA and training environment for producing deployable artifacts.
notebook/mentalhealthdatasetEDA.ipynb - Train model · Notebook-based model training and artifact generation.
notebook/train_model.ipynb - Survey data · Training and analysis dataset used by the notebooks.
notebook/survey.csv - Notebook model · Training-time model artifact used to produce the committed runtime pickle.
notebook/final_model.pkl - Notebook encoders · Training-time preprocessing artifact used to produce the committed runtime pickle.
notebook/encoders.pkl
Auth & Storage
User identity, session state, and persisted assessment history.
- Auth flow · Local credentials and federated sign-in path into the app.
- SQLite DB · Application database for users and assessment history.
- Google OAuth · Federated authentication integration configured through the environment.
- PDF export · Generated assessment report output derived from results and explanation data.
Connections 29
- app.py → Base layout: renders · Common page layout used by all screens.
- app.py → Landing page: serves · Landing page route.
- app.py → Login page: serves · Authentication page route.
- app.py → Register page: serves · Account creation page route.
- app.py → Dashboard: serves · Assessment form route.
- app.py → Result page: serves · Prediction result route.
- app.py → History page: serves · Assessment history route.
- app.py → Legal page: serves · Static policy and legal page.
- app.py → Stylesheet: uses · Shared UI styling.
- app.py → Procfile: deploys with · Process definition for hosted execution.
- app.py → model_utils.py: calls · Delegates prediction work to the ML layer.
- app.py → Auth flow: coordinates · Handles both local and federated authentication flows.
- Auth flow → SQLite DB: stores users · Persists credentials and user records.
- Auth flow → Google OAuth: federates · Uses Google OAuth for external sign-in.
- app.py → SQLite DB: reads/writes · Stores and retrieves user-specific assessment history.
- model_utils.py → XGBoost model: loads · Runtime classifier artifact.
- model_utils.py → Encoders: loads · Runtime preprocessing artifact.
- model_utils.py → SHAP explain: computes · Derives per-feature explanation output.
- app.py → PDF export: exports · Produces downloadable report output from assessment results.
- Notebooks → Survey data: analyzes · EDA and training inputs.
- Train model → Survey data: trains on · Consumes dataset for model fitting.
- Train model → Notebook model: produces · Creates training-time model artifact.
- Train model → Notebook encoders: produces · Creates training-time preprocessing artifact.
- Notebook model → XGBoost model: publishes · Notebook artifact is carried into the runtime model file.
- Notebook encoders → Encoders: publishes · Notebook artifact is carried into the runtime encoders file.
- app.py → Dashboard: collects input · User assessment data is submitted through the dashboard form.
- Dashboard → model_utils.py: feeds features · Assessment inputs are transformed into model features.
- model_utils.py → Result page: returns result · Prediction and explanation payload is rendered for the user.
- app.py → History page: shows history · History view reflects stored assessment records.