# piyushb03/mind-sphere architecture

> Architecture diagram of the GitHub repository piyushb03/mind-sphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piyushb03/mind-sphere
- Repository: https://github.com/piyushb03/mind-sphere

## Overview

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`](https://github.com/piyushb03/mind-sphere/blob/main/app.py) (app.py), [`model_utils.py`](https://github.com/piyushb03/mind-sphere/blob/main/model_utils.py) (model_utils.py), [`notebook/train_model.ipynb`](https://github.com/piyushb03/mind-sphere/blob/main/notebook/train_model.ipynb) (Train model), [`templates/dashboard.html`](https://github.com/piyushb03/mind-sphere/blob/main/templates/dashboard.html) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web UI"]
  node_templates_base["Base layout<br/>shared template<br/>[base.html]"]
  node_templates_index["Landing page<br/>template<br/>[index.html]"]
  node_templates_login["Login page<br/>template<br/>[login.html]"]
  node_templates_register["Register page<br/>template<br/>[register.html]"]
  node_templates_dashboard["Dashboard<br/>template<br/>[dashboard.html]"]
  node_templates_result["Result page<br/>template<br/>[result.html]"]
  node_templates_history["History page<br/>template<br/>[history.html]"]
  node_templates_legal["Legal page<br/>template<br/>[legal.html]"]
  node_style_css["Stylesheet<br/>static css<br/>[style.css]"]
end

subgraph group_app["Flask App"]
  node_app_py["app.py<br/>flask entrypoint<br/>[app.py]"]
  node_procfile["Procfile<br/>deploy process"]
end

subgraph group_ml["ML Serving"]
  node_model_utils_py["model_utils.py<br/>inference service<br/>[model_utils.py]"]
  node_final_model[("XGBoost model<br/>serialized classifier<br/>[final_model.pkl]")]
  node_encoders[("Encoders<br/>serialized preprocessing<br/>[encoders.pkl]")]
  node_shap_explain(("SHAP explain<br/>explainability"))
end

subgraph group_data["Training Workspace"]
  node_notebooks["Notebooks<br/>training workspace"]
  node_train_model["Train model<br/>offline training<br/>[train_model.ipynb]"]
  node_survey[("Survey data<br/>dataset<br/>[survey.csv]")]
  node_nb_model[("Notebook model<br/>artifact<br/>[final_model.pkl]")]
  node_nb_encoders[("Notebook encoders<br/>artifact<br/>[encoders.pkl]")]
end

subgraph group_platform["Auth & Storage"]
  node_auth{{"Auth flow<br/>login/oauth"}}
  node_db[("SQLite DB<br/>persistent store")]
  node_oauth{{"Google OAuth<br/>external identity"}}
  node_pdf["PDF export<br/>report output"]
end

node_app_py -->|"renders"| node_templates_base
node_app_py -->|"serves"| node_templates_index
node_app_py -->|"serves"| node_templates_login
node_app_py -->|"serves"| node_templates_register
node_app_py -->|"serves"| node_templates_dashboard
node_app_py -->|"serves"| node_templates_result
node_app_py -->|"serves"| node_templates_history
node_app_py -->|"serves"| node_templates_legal
node_app_py -->|"uses"| node_style_css
node_app_py -->|"deploys with"| node_procfile
node_app_py -->|"calls"| node_model_utils_py
node_app_py -->|"coordinates"| node_auth
node_auth -->|"stores users"| node_db
node_auth -->|"federates"| node_oauth
node_app_py -->|"reads/writes"| node_db
node_model_utils_py -->|"loads"| node_final_model
node_model_utils_py -->|"loads"| node_encoders
node_model_utils_py -->|"computes"| node_shap_explain
node_app_py -->|"exports"| node_pdf
node_notebooks -->|"analyzes"| node_survey
node_train_model -->|"trains on"| node_survey
node_train_model -->|"produces"| node_nb_model
node_train_model -->|"produces"| node_nb_encoders
node_nb_model -->|"publishes"| node_final_model
node_nb_encoders -->|"publishes"| node_encoders
node_app_py -->|"collects input"| node_templates_dashboard
node_templates_dashboard -->|"feeds features"| node_model_utils_py
node_model_utils_py -->|"returns result"| node_templates_result
node_app_py -->|"shows history"| node_templates_history

click node_app_py "https://github.com/piyushb03/mind-sphere/blob/main/app.py"
click node_model_utils_py "https://github.com/piyushb03/mind-sphere/blob/main/model_utils.py"
click node_templates_base "https://github.com/piyushb03/mind-sphere/blob/main/templates/base.html"
click node_templates_index "https://github.com/piyushb03/mind-sphere/blob/main/templates/index.html"
click node_templates_login "https://github.com/piyushb03/mind-sphere/blob/main/templates/login.html"
click node_templates_register "https://github.com/piyushb03/mind-sphere/blob/main/templates/register.html"
click node_templates_dashboard "https://github.com/piyushb03/mind-sphere/blob/main/templates/dashboard.html"
click node_templates_result "https://github.com/piyushb03/mind-sphere/blob/main/templates/result.html"
click node_templates_history "https://github.com/piyushb03/mind-sphere/blob/main/templates/history.html"
click node_templates_legal "https://github.com/piyushb03/mind-sphere/blob/main/templates/legal.html"
click node_style_css "https://github.com/piyushb03/mind-sphere/blob/main/static/css/style.css"
click node_procfile "https://github.com/piyushb03/mind-sphere/tree/main/Procfile"
click node_final_model "https://github.com/piyushb03/mind-sphere/blob/main/models/final_model.pkl"
click node_encoders "https://github.com/piyushb03/mind-sphere/blob/main/models/encoders.pkl"
click node_notebooks "https://github.com/piyushb03/mind-sphere/blob/main/notebook/mentalhealthdatasetEDA.ipynb"
click node_train_model "https://github.com/piyushb03/mind-sphere/blob/main/notebook/train_model.ipynb"
click node_survey "https://github.com/piyushb03/mind-sphere/blob/main/notebook/survey.csv"
click node_nb_model "https://github.com/piyushb03/mind-sphere/blob/main/notebook/final_model.pkl"
click node_nb_encoders "https://github.com/piyushb03/mind-sphere/blob/main/notebook/encoders.pkl"

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_templates_base,node_templates_index,node_templates_login,node_templates_register,node_templates_dashboard,node_templates_result,node_templates_history,node_templates_legal,node_style_css toneBlue
class node_app_py,node_procfile toneAmber
class node_model_utils_py,node_final_model,node_encoders,node_shap_explain toneMint
class node_notebooks,node_train_model,node_survey,node_nb_model,node_nb_encoders toneRose
class node_auth,node_db,node_oauth,node_pdf toneIndigo
```

## Components

### Web UI

Server-rendered pages and shared styling for the assessment experience.

- [Base layout](https://github.com/piyushb03/mind-sphere/blob/main/templates/base.html): shared template · Common page shell used by the rendered views. · `templates/base.html`
- [Landing page](https://github.com/piyushb03/mind-sphere/blob/main/templates/index.html): template · Entry screen for the app and first user touchpoint. · `templates/index.html`
- [Login page](https://github.com/piyushb03/mind-sphere/blob/main/templates/login.html): template · Local sign-in screen for authenticated access. · `templates/login.html`
- [Register page](https://github.com/piyushb03/mind-sphere/blob/main/templates/register.html): template · Account creation screen for local credentials. · `templates/register.html`
- [Dashboard](https://github.com/piyushb03/mind-sphere/blob/main/templates/dashboard.html): template · Assessment form where user inputs are collected. · `templates/dashboard.html`
- [Result page](https://github.com/piyushb03/mind-sphere/blob/main/templates/result.html): template · Prediction output and explanation view. · `templates/result.html`
- [History page](https://github.com/piyushb03/mind-sphere/blob/main/templates/history.html): template · Past assessments and prior results for a user. · `templates/history.html`
- [Legal page](https://github.com/piyushb03/mind-sphere/blob/main/templates/legal.html): template · Static legal and policy content. · `templates/legal.html`
- [Stylesheet](https://github.com/piyushb03/mind-sphere/blob/main/static/css/style.css): static css · Shared presentation layer for the server-rendered UI. · `static/css/style.css`

### Flask App

Request handling, orchestration, and user-facing flows.

- [app.py](https://github.com/piyushb03/mind-sphere/blob/main/app.py): flask entrypoint · Main web application entry point and flow coordinator. · `app.py`
- [Procfile](https://github.com/piyushb03/mind-sphere/tree/main/Procfile): deploy process · Process entry definition for deployment hosting. · `Procfile`

### ML Serving

Model loading, preprocessing, prediction, and explainability.

- [model_utils.py](https://github.com/piyushb03/mind-sphere/blob/main/model_utils.py): inference service · Loads model assets, prepares features, and produces predictions plus explanations. · `model_utils.py`
- [XGBoost model](https://github.com/piyushb03/mind-sphere/blob/main/models/final_model.pkl): serialized classifier · Committed production model artifact used at inference time. · `models/final_model.pkl`
- [Encoders](https://github.com/piyushb03/mind-sphere/blob/main/models/encoders.pkl): serialized preprocessing · Saved categorical encoders used to align form inputs with model features. · `models/encoders.pkl`
- **SHAP explain**: explainability · Feature attribution layer that turns predictions into per-input explanations.

### Training Workspace

Offline notebook environment and generated model assets.

- [Notebooks](https://github.com/piyushb03/mind-sphere/blob/main/notebook/mentalhealthdatasetEDA.ipynb): training workspace · Offline EDA and training environment for producing deployable artifacts. · `notebook/mentalhealthdatasetEDA.ipynb`
- [Train model](https://github.com/piyushb03/mind-sphere/blob/main/notebook/train_model.ipynb): offline training · Notebook-based model training and artifact generation. · `notebook/train_model.ipynb`
- [Survey data](https://github.com/piyushb03/mind-sphere/blob/main/notebook/survey.csv): dataset · Training and analysis dataset used by the notebooks. · `notebook/survey.csv`
- [Notebook model](https://github.com/piyushb03/mind-sphere/blob/main/notebook/final_model.pkl): artifact · Training-time model artifact used to produce the committed runtime pickle. · `notebook/final_model.pkl`
- [Notebook encoders](https://github.com/piyushb03/mind-sphere/blob/main/notebook/encoders.pkl): artifact · 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**: login/oauth · Local credentials and federated sign-in path into the app.
- **SQLite DB**: persistent store · Application database for users and assessment history.
- **Google OAuth**: external identity · Federated authentication integration configured through the environment.
- **PDF export**: report output · Generated assessment report output derived from results and explanation data.

## Connections

- 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.
