# qusay13/mindmate architecture

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

- Interactive diagram: https://gitdiagram.com/qusay13/mindmate
- Repository: https://github.com/qusay13/mindmate

## Overview

1. **Overall shape**
   - MindMate is a **monorepo with a Django backend + React frontend**.
   - The backend is a **modular Django monolith** split into domain apps, while the frontend is a separate **Vite/React SPA** in `front/`.

2. **Backend runtime and entry points**
   - The Django project lives under `config/` with `settings.py`, `urls.py`, `asgi.py`, and `wsgi.py`.
   - `asgi.py` is important because the system runs **both REST APIs and WebSocket chat** through Django Channels.
   - `manage.py` is the main management entry point for migrations, seeding, and maintenance commands.

3. **Authentication and identity**
   - `accounts/` is the identity boundary: registration, login/token auth, user profile management, and role-specific fields for patients/doctors.
   - It also includes custom authentication logic and admin integration.
   - This app is the upstream dependency for most other modules because nearly every feature is user-scoped and permissioned.

4. **Clinical workflow and doctor-patient relationships**
   - `clinic/` manages the **relationship layer** between patients and doctors.
   - It contains services like `doctor_service.py` and `recommendation_service.py`, which suggests this app is where **matching/recommendation logic** is centralized.
   - The readme indicates the system recommends doctors based on the patient’s worst severity over the last 30 days, so `clinic` depends on tracking/assessment outputs.

5. **Daily tracking and longitudinal analysis**
   - `tracking/` is the core patient data subsystem for **mood entries, journals, and questionnaire answers**.
   - It includes a dedicated `analysis_service.py`, showing that computation is separated from views/models.
   - The app also has management commands to load questionnaires and seed test data, which implies tracked data and survey definitions are part of its operational model.

6. **Assessment and symptom scoring**
   - `assessment/` appears to own **clinical questionnaire evaluation logic**, with `journal_assessment_service.py` and related models/views.
   - The readme specifically references medical algorithms such as **PHQ-9** and **GAD-7**, and the repo includes external analysis assets for that purpose.
   - This app likely transforms raw questionnaire/journal input into severity classifications consumed by recommendation and dashboards.

7. **Survey intake**
   - `survey/` is a separate intake module for the **initial onboarding survey**.
   - It sits earlier in the patient journey than tracking/assessment and likely populates baseline clinical data used later by the recommendation and analysis layers.

8. **Chat, chatbot, and real-time communication**
   - `chat/` implements **real-time doctor-patient messaging** using **WebSockets** via `consumers.py`, `routing.py`, and ASGI integration.
   - `chatbot/` is a separate AI-assisted conversation channel, with `services/ai_service.py` indicating an external or model-backed response layer.
   - These are distinct communication paths: one is human-to-human real-time chat, the other is automated assistant logic.

9. **Notifications**
   - `notifications/` is the cross-cutting event delivery layer.
   - It likely reacts to events from accounts, clinic, chat, and tracking to notify users about new messages, relationship requests, or assessment-related updates.
   - Because it has its own services layer, notifications are treated as a first-class subsystem rather than just inline view logic.

10. **External analysis dependency**
   - `external/journal_analyzer/engine.py` and the documented RaedRepo integration indicate a separate **clinical analysis engine boundary**.
   - This is likely invoked by assessment/tracking services rather than exposed directly to the UI.
   - Its presence means some medical logic is intentionally isolated from the main app codebase, which matters for the architecture diagram.

11. **Frontend architecture**
   - `front/` is a **single-page app** built with React and Vite.
   - It has page-level views for patient, doctor, admin, chat, clinic, survey, and analysis workflows.
   - `src/context/AuthContext.jsx` and `src/services/api.js` show a centralized auth/session and API access layer rather than direct per-page networking.

12. **Primary end-to-end flows**
   - A typical patient flow is: **register/login → fill survey → daily tracking/journaling → assessment/analysis → doctor recommendation → optionally share with doctor**.
   - A doctor flow is: **authenticate → review linked patients/requests → view tracking summaries/analysis → communicate via chat**.
   - An admin flow exists for **account oversight and platform-level statistics**.

13. **Data and infrastructure boundaries**
   - Persistence is centered on **PostgreSQL in production** with SQLite for local development, and the repo includes SQL/db fix artifacts and a Redis dump file.
   - Redis is not just incidental: it is part of the **Channels/WebSocket runtime** and likely supports session or async messaging behavior.
   - `daphne` is the expected ASGI server, which is critical for diagramming the real-time path.

14. **Operational tooling and supporting assets**
   - The repository contains API documentation/schema assets (`schema.json`, Postman environment, Swagger/OpenAPI support) and several test scripts for API flows.
   - There are also seeding and repair utilities such as `setup_demo_data.py`, `fix_questionnaire_answers.py`, and `fix_severity_levels.py`, which indicate active data maintenance around clinical datasets.
   - The output docs/diagrams folders suggest the project has already been analyzed/generated into UML artifacts, but the source of truth is still the Django app structure above.

Main entry points: [`front/src/services/api.js`](https://github.com/qusay13/mindmate/blob/main/front/src/services/api.js) (API client), [`mindmate_db_v4.1_final.sql`](https://github.com/qusay13/mindmate/blob/main/mindmate_db_v4.1_final.sql) (Postgres), [`front/src/context/AuthContext.jsx`](https://github.com/qusay13/mindmate/blob/main/front/src/context/AuthContext.jsx) (Auth context), [`external/journal_analyzer/engine.py`](https://github.com/qusay13/mindmate/blob/main/external/journal_analyzer/engine.py) (Analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_manage_py["manage.py<br/>django entrypoint<br/>[manage.py]"]
  node_config["Config<br/>django project"]
  node_accounts["Accounts<br/>identity app"]
  node_survey["Survey<br/>intake app"]
  node_tracking["Tracking<br/>longitudinal app"]
  node_assessment["Assessment<br/>scoring app"]
  node_clinic["Clinic<br/>care coordination"]
  node_chat["Chat<br/>realtime messaging"]
  node_chatbot["Chatbot<br/>ai assistant"]
  node_notifications["Notifications<br/>event delivery"]
end

subgraph group_frontend["Frontend"]
  node_auth_ctx["Auth context<br/>frontend state<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>frontend service<br/>[api.js]"]
  node_login_page["Login<br/>frontend page<br/>[LoginPage.jsx]"]
  node_survey_page["Survey<br/>frontend page<br/>[SurveyPage.jsx]"]
  node_tracking_page["Journal<br/>frontend page"]
  node_analysis_page["Analysis<br/>frontend page<br/>[AnalysisPage.jsx]"]
  node_clinic_page["Clinic<br/>frontend page<br/>[ClinicPage.jsx]"]
  node_chat_page["Chat<br/>frontend page<br/>[ChatPage.jsx]"]
  node_doctor_dash["Doctor dashboard<br/>frontend page"]
  node_admin_dash["Admin dashboard<br/>frontend page<br/>[AdminDashboard.jsx]"]
end

subgraph group_external["External boundary"]
  node_external_engine{{"Analyzer<br/>external engine<br/>[engine.py]"}}
  node_redis[("Redis<br/>async runtime<br/>[dump.rdb]")]
  node_postgres[("Postgres<br/>primary database")]
end

node_manage_py -->|"boots"| node_config
node_config -->|"installs"| node_accounts
node_config -->|"installs"| node_survey
node_config -->|"installs"| node_tracking
node_config -->|"installs"| node_assessment
node_config -->|"installs"| node_clinic
node_config -->|"installs"| node_chat
node_config -->|"installs"| node_chatbot
node_config -->|"installs"| node_notifications
node_accounts -->|"supplies identity"| node_clinic
node_accounts -->|"authenticates"| node_tracking
node_survey -->|"seeds baseline"| node_tracking
node_tracking -->|"feeds scores"| node_assessment
node_assessment -->|"informs recommendations"| node_clinic
node_tracking -->|"analyzes via"| node_external_engine
node_assessment -->|"uses"| node_external_engine
node_clinic -->|"coordinates"| node_chat
node_chat -->|"uses"| node_redis
node_chat -->|"emits"| node_notifications
node_tracking -->|"emits"| node_notifications
node_clinic -->|"emits"| node_notifications
node_accounts -->|"persists"| node_postgres
node_survey -->|"persists"| node_postgres
node_tracking -->|"persists"| node_postgres
node_assessment -->|"persists"| node_postgres
node_clinic -->|"persists"| node_postgres
node_chat -->|"persists"| node_postgres
node_notifications -->|"persists"| node_postgres
node_api_client -->|"calls"| node_accounts
node_api_client -->|"calls"| node_survey
node_api_client -->|"calls"| node_tracking
node_api_client -->|"calls"| node_assessment
node_api_client -->|"calls"| node_clinic
node_api_client -->|"calls"| node_chat
node_api_client -->|"calls"| node_chatbot
node_auth_ctx -->|"wraps"| node_api_client
node_login_page -->|"uses"| node_auth_ctx
node_survey_page -->|"uses"| node_api_client
node_tracking_page -->|"uses"| node_api_client
node_analysis_page -->|"uses"| node_api_client
node_clinic_page -->|"uses"| node_api_client
node_chat_page -->|"uses"| node_api_client
node_doctor_dash -->|"uses"| node_api_client
node_admin_dash -->|"uses"| node_api_client

click node_manage_py "https://github.com/qusay13/mindmate/blob/main/manage.py"
click node_auth_ctx "https://github.com/qusay13/mindmate/blob/main/front/src/context/AuthContext.jsx"
click node_api_client "https://github.com/qusay13/mindmate/blob/main/front/src/services/api.js"
click node_login_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/LoginPage.jsx"
click node_survey_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/SurveyPage.jsx"
click node_tracking_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/DailyAssessmentPage.jsx"
click node_analysis_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/AnalysisPage.jsx"
click node_clinic_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/ClinicPage.jsx"
click node_chat_page "https://github.com/qusay13/mindmate/blob/main/front/src/pages/ChatPage.jsx"
click node_doctor_dash "https://github.com/qusay13/mindmate/blob/main/front/src/pages/DoctorDashboard.jsx"
click node_admin_dash "https://github.com/qusay13/mindmate/blob/main/front/src/pages/AdminDashboard.jsx"
click node_external_engine "https://github.com/qusay13/mindmate/blob/main/external/journal_analyzer/engine.py"
click node_redis "https://github.com/qusay13/mindmate/blob/main/dump.rdb"
click node_postgres "https://github.com/qusay13/mindmate/blob/main/mindmate_db_v4.1_final.sql"

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_manage_py,node_config,node_accounts,node_survey,node_tracking,node_assessment,node_clinic,node_chat,node_chatbot,node_notifications toneBlue
class node_auth_ctx,node_api_client,node_login_page,node_survey_page,node_tracking_page,node_analysis_page,node_clinic_page,node_chat_page,node_doctor_dash,node_admin_dash toneAmber
class node_external_engine,node_redis,node_postgres toneMint
```

## Components

### Backend

Django monolith, domain apps, and real-time runtime

- [manage.py](https://github.com/qusay13/mindmate/blob/main/manage.py): django entrypoint · Management commands for migrations, seeding, and maintenance · `manage.py`
- **Config**: django project · Project settings, URL routing, and ASGI/WSGI entrypoints
- **Accounts**: identity app · Registration, login, roles, profiles, and authentication
- **Survey**: intake app · Onboarding survey and baseline patient data capture
- **Tracking**: longitudinal app · Mood entries, journals, questionnaires, and analysis support
- **Assessment**: scoring app · Questionnaire evaluation and severity classification
- **Clinic**: care coordination · Patient-doctor relationships, matching, and recommendations
- **Chat**: realtime messaging · WebSocket-based doctor-patient messaging
- **Chatbot**: ai assistant · Automated conversational assistant and AI response layer
- **Notifications**: event delivery · Cross-cutting user notification services

### Frontend

React/Vite single-page application

- [Auth context](https://github.com/qusay13/mindmate/blob/main/front/src/context/AuthContext.jsx): frontend state · Centralized session and auth state management · `front/src/context/AuthContext.jsx`
- [API client](https://github.com/qusay13/mindmate/blob/main/front/src/services/api.js): frontend service · Shared HTTP access layer for backend APIs · `front/src/services/api.js`
- [Login](https://github.com/qusay13/mindmate/blob/main/front/src/pages/LoginPage.jsx): frontend page · User sign-in entry screen · `front/src/pages/LoginPage.jsx`
- [Survey](https://github.com/qusay13/mindmate/blob/main/front/src/pages/SurveyPage.jsx): frontend page · Onboarding survey workflow · `front/src/pages/SurveyPage.jsx`
- [Journal](https://github.com/qusay13/mindmate/blob/main/front/src/pages/DailyAssessmentPage.jsx): frontend page · Daily assessment, history, and longitudinal tracking screens · `front/src/pages/DailyAssessmentPage.jsx`
- [Analysis](https://github.com/qusay13/mindmate/blob/main/front/src/pages/AnalysisPage.jsx): frontend page · Assessment and severity review screen · `front/src/pages/AnalysisPage.jsx`
- [Clinic](https://github.com/qusay13/mindmate/blob/main/front/src/pages/ClinicPage.jsx): frontend page · Doctor-patient matching and relationship screens · `front/src/pages/ClinicPage.jsx`
- [Chat](https://github.com/qusay13/mindmate/blob/main/front/src/pages/ChatPage.jsx): frontend page · Human-to-human messaging screen · `front/src/pages/ChatPage.jsx`
- [Doctor dashboard](https://github.com/qusay13/mindmate/blob/main/front/src/pages/DoctorDashboard.jsx): frontend page · Doctor workflow and linked patient review · `front/src/pages/DoctorDashboard.jsx`
- [Admin dashboard](https://github.com/qusay13/mindmate/blob/main/front/src/pages/AdminDashboard.jsx): frontend page · Platform oversight and statistics · `front/src/pages/AdminDashboard.jsx`

### External boundary

Analysis engine and infrastructure dependencies

- [Analyzer](https://github.com/qusay13/mindmate/blob/main/external/journal_analyzer/engine.py): external engine · Isolated journal analysis engine boundary · `external/journal_analyzer/engine.py`
- [Redis](https://github.com/qusay13/mindmate/blob/main/dump.rdb): async runtime · WebSocket and async messaging support · `dump.rdb`
- [Postgres](https://github.com/qusay13/mindmate/blob/main/mindmate_db_v4.1_final.sql): primary database · Production relational data store · `mindmate_db_v4.1_final.sql`

## Connections

- manage.py → Config: boots · Runs Django management lifecycle against the project configuration
- Config → Accounts: installs · Registers identity and auth services in the Django project
- Config → Survey: installs · Registers onboarding survey routes and models
- Config → Tracking: installs · Registers longitudinal tracking features
- Config → Assessment: installs · Registers severity scoring and assessment logic
- Config → Clinic: installs · Registers doctor-patient coordination features
- Config → Chat: installs · Enables ASGI and WebSocket chat routing
- Config → Chatbot: installs · Exposes assistant conversation endpoints
- Config → Notifications: installs · Registers platform notification delivery
- Accounts → Clinic: supplies identity · User roles and profiles drive care coordination
- Accounts → Tracking: authenticates · Tracked data is user-scoped
- Survey → Tracking: seeds baseline · Onboarding inputs feed later longitudinal data
- Tracking → Assessment: feeds scores · Journal and questionnaire data are evaluated into severity
- Assessment → Clinic: informs recommendations · Severity output helps match and recommend doctors
- Tracking → Analyzer: analyzes via · Delegates clinical analysis to an isolated engine boundary
- Assessment → Analyzer: uses · Clinical algorithms are partly isolated from app code
- Clinic → Chat: coordinates · Linked patients and doctors communicate through chat
- Chat → Redis: uses · Supports ASGI/WebSocket runtime and async messaging
- Chat → Notifications: emits · New messages can trigger user notifications
- Tracking → Notifications: emits · Assessment or journal events may notify users
- Clinic → Notifications: emits · Relationship and recommendation events may notify users
- Accounts → Postgres: persists · Identity and profile data are stored relationally
- Survey → Postgres: persists · Survey responses are stored in the database
- Tracking → Postgres: persists · Mood, journal, and questionnaire data are stored
- Assessment → Postgres: persists · Scoring outputs and related records are stored
- Clinic → Postgres: persists · Doctor-patient relationships and ratings are stored
- Chat → Postgres: persists · Conversation data is stored relationally
- Notifications → Postgres: persists · Notification records and delivery state are stored
- API client → Accounts: calls · Shared frontend API client talks to backend auth endpoints
- API client → Survey: calls · Shared frontend API client talks to survey endpoints
- API client → Tracking: calls · Shared frontend API client talks to tracking endpoints
- API client → Assessment: calls · Shared frontend API client talks to assessment endpoints
- API client → Clinic: calls · Shared frontend API client talks to clinic endpoints
- API client → Chat: calls · Shared frontend API client talks to chat endpoints
- API client → Chatbot: calls · Shared frontend API client talks to chatbot endpoints
- Auth context → API client: wraps · Session-aware state feeds API requests
- Login → Auth context: uses · Login updates centralized auth state
- Survey → API client: uses · Survey workflow submits onboarding data
- Journal → API client: uses · Daily assessment and history screens load tracking data
- Analysis → API client: uses · Analysis screen retrieves scoring and severity data
- Clinic → API client: uses · Clinic screen loads doctor-patient relationship data
- Chat → API client: uses · Chat screen loads conversation state
- Doctor dashboard → API client: uses · Doctor dashboard retrieves linked patient summaries
- Admin dashboard → API client: uses · Admin dashboard retrieves platform oversight data
