# sirivalli-stack/mental-health-agent architecture

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

- Interactive diagram: https://gitdiagram.com/sirivalli-stack/mental-health-agent
- Repository: https://github.com/sirivalli-stack/mental-health-agent

## Overview

This is a research prototype for state-aware conversational mental-health support, not a clinical system. The main workflow is a user chat turn through the React interface and API, pre-generation safety, sentiment/emotion/risk analysis and session-state assembly, LLM response generation, then post-generation safety and presentation. Separate branches cover persistent memory and personalization, model training, and health/status reporting. Relationships reflect the excerpts, SOURCE INDEX references, or README; some wiring is documented rather than shown in sampled code.

Main entry points: [`backend/app/state_engine/engine.py`](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/engine.py) (User state engine), [`backend/app/pipelines/chat.py`](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/pipelines/chat.py) (Chat pipeline), [`backend/app/api/chat.py`](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/api/chat.py) (Chat endpoint), [`backend/app/training/text_normalise.py`](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/training/text_normalise.py) (Text normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_webapp["Chat interface<br/>[App.jsx]"]
  node_webapi["Frontend API<br/>[api.js]"]
end

subgraph group_runtime["Conversation runtime"]
  node_chatapi["Chat endpoint<br/>[chat.py]"]
  node_chatpipe["Chat pipeline<br/>[chat.py]"]
  node_schemas["Request and state contracts<br/>[schemas.py]"]
  node_presafety["Pre-generation safety<br/>[pre_generation.py]"]
  node_llm["LLM generation<br/>[llm_service.py]"]
  node_postsafety["Post-generation safety<br/>[post_generation.py]"]
end

subgraph group_state["State and memory"]
  node_stateengine["User state engine<br/>[engine.py]"]
  node_trends["Trajectory trends<br/>[trends.py]"]
  node_sessionstore["Session state store<br/>[store.py]"]
  node_memory["Conversation memory<br/>[store.py]"]
  node_database[("SQLite session database<br/>[db.py]")]
  node_personalization["Profile extraction<br/>[extractor.py]"]
end

subgraph group_models["Inference and training"]
  node_sentiment["Sentiment analysis"]
  node_emotion["Emotion analysis<br/>[emotion_service.py]"]
  node_risk["Risk analysis<br/>[risk_service.py]"]
  node_training["Classifier training"]
  node_normalise["Text normalization<br/>[text_normalise.py]"]
end

subgraph group_operations["Safety and operations"]
  node_rules["Risk rules<br/>[rules.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_turnlog[("Turn audit log<br/>[turn_log.py]")]
end

node_user(("User"))
node_llmservice{{"Local LLM service"}}

node_user -->|"sends message"| node_webapp
node_webapp -->|"submits chat"| node_webapi
node_webapi -->|"calls chat API"| node_chatapi
node_chatapi -->|"dispatches turn"| node_chatpipe
node_chatapi -->|"validates request"| node_schemas
node_chatpipe -->|"checks input"| node_presafety
node_chatpipe -->|"builds state"| node_stateengine
node_stateengine -->|"infers sentiment"| node_sentiment
node_stateengine -->|"infers emotion"| node_emotion
node_stateengine -->|"infers risk"| node_risk
node_risk -->|"applies rules"| node_rules
node_stateengine -->|"computes trends"| node_trends
node_stateengine -->|"reads and updates"| node_sessionstore
node_stateengine -->|"recalls session"| node_memory
node_stateengine -->|"extracts profile"| node_personalization
node_memory -->|"persists snapshots"| node_database
node_chatpipe -->|"generates reply"| node_llm
node_llm -->|"sends prompt"| node_llmservice
node_chatpipe -->|"checks draft"| node_postsafety
node_chatpipe -->|"records turn"| node_turnlog
node_webapi -->|"checks service status"| node_health
node_training -->|"uses preprocessing"| node_normalise
node_sentiment -->|"uses preprocessing"| node_normalise
node_emotion -->|"uses preprocessing"| node_normalise
node_risk -->|"uses preprocessing"| node_normalise
node_chatapi -.->|"returns response"| node_webapp

click node_webapp "https://github.com/sirivalli-stack/mental-health-agent/blob/main/frontend/src/App.jsx"
click node_webapi "https://github.com/sirivalli-stack/mental-health-agent/blob/main/frontend/src/api.js"
click node_chatapi "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/api/chat.py"
click node_chatpipe "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/pipelines/chat.py"
click node_schemas "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/models/schemas.py"
click node_presafety "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/pre_generation.py"
click node_llm "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/llm_service.py"
click node_postsafety "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/post_generation.py"
click node_stateengine "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/engine.py"
click node_sentiment "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/sentiment_service.py"
click node_emotion "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/emotion_service.py"
click node_risk "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/risk_service.py"
click node_rules "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/rules.py"
click node_trends "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/trends.py"
click node_sessionstore "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/store.py"
click node_memory "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/memory/store.py"
click node_database "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/models/db.py"
click node_personalization "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/personalization/extractor.py"
click node_training "https://github.com/sirivalli-stack/mental-health-agent/tree/main/backend/app/training"
click node_normalise "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/training/text_normalise.py"
click node_health "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/api/health.py"
click node_turnlog "https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/pipelines/turn_log.py"

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_webapp,node_webapi,node_user toneBlue
class node_chatapi,node_chatpipe,node_schemas,node_presafety,node_llm,node_postsafety toneAmber
class node_stateengine,node_trends,node_sessionstore,node_memory,node_database,node_personalization toneMint
class node_sentiment,node_emotion,node_risk,node_training,node_normalise toneRose
class node_rules,node_health,node_turnlog,node_llmservice toneIndigo
```

## Components

### Chat experience

- [Chat interface](https://github.com/sirivalli-stack/mental-health-agent/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Frontend API](https://github.com/sirivalli-stack/mental-health-agent/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Conversation runtime

- [Chat endpoint](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Chat pipeline](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/pipelines/chat.py): `backend/app/pipelines/chat.py`
- [Request and state contracts](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Pre-generation safety](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/pre_generation.py): `backend/app/safety/pre_generation.py`
- [LLM generation](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`
- [Post-generation safety](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/post_generation.py): `backend/app/safety/post_generation.py`

### State and memory

- [User state engine](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/engine.py): `backend/app/state_engine/engine.py`
- [Trajectory trends](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/trends.py): `backend/app/state_engine/trends.py`
- [Session state store](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/state_engine/store.py): `backend/app/state_engine/store.py`
- [Conversation memory](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/memory/store.py): `backend/app/memory/store.py`
- [SQLite session database](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/models/db.py): `backend/app/models/db.py`
- [Profile extraction](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/personalization/extractor.py): `backend/app/personalization/extractor.py`

### Inference and training

- [Sentiment analysis](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/sentiment_service.py): `backend/app/services/sentiment_service.py`
- [Emotion analysis](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/emotion_service.py): `backend/app/services/emotion_service.py`
- [Risk analysis](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/services/risk_service.py): `backend/app/services/risk_service.py`
- [Classifier training](https://github.com/sirivalli-stack/mental-health-agent/tree/main/backend/app/training): `backend/app/training`
- [Text normalization](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/training/text_normalise.py): `backend/app/training/text_normalise.py`

### Safety and operations

- [Risk rules](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/safety/rules.py): `backend/app/safety/rules.py`
- [Health endpoint](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/api/health.py): `backend/app/api/health.py`
- [Turn audit log](https://github.com/sirivalli-stack/mental-health-agent/blob/main/backend/app/pipelines/turn_log.py): `backend/app/pipelines/turn_log.py`

### Other components

- **User**
- **Local LLM service**

## Connections

- User → Chat interface: sends message (evidence: `frontend/src/App.jsx`)
- Chat interface → Frontend API: submits chat (evidence: `frontend/src/App.jsx`)
- Frontend API → Chat endpoint: calls chat API (evidence: `README.md`)
- Chat endpoint → Chat pipeline: dispatches turn (evidence: `backend/app/api/chat.py`)
- Chat endpoint → Request and state contracts: validates request (evidence: `backend/app/api/chat.py`)
- Chat pipeline → Pre-generation safety: checks input (evidence: `backend/app/pipelines/chat.py`)
- Chat pipeline → User state engine: builds state (evidence: `backend/app/pipelines/chat.py`)
- User state engine → Sentiment analysis: infers sentiment (evidence: `backend/app/state_engine/engine.py`)
- User state engine → Emotion analysis: infers emotion (evidence: `backend/app/state_engine/engine.py`)
- User state engine → Risk analysis: infers risk (evidence: `backend/app/state_engine/engine.py`)
- Risk analysis → Risk rules: applies rules (evidence: `backend/app/services/risk_service.py`)
- User state engine → Trajectory trends: computes trends (evidence: `backend/app/state_engine/engine.py`)
- User state engine → Session state store: reads and updates (evidence: `backend/app/state_engine/engine.py`)
- User state engine → Conversation memory: recalls session (evidence: `backend/app/state_engine/engine.py`)
- User state engine → Profile extraction: extracts profile (evidence: `backend/app/state_engine/engine.py`)
- Conversation memory → SQLite session database: persists snapshots (evidence: `backend/app/memory/store.py`)
- Chat pipeline → LLM generation: generates reply (evidence: `backend/app/pipelines/chat.py`)
- LLM generation → Local LLM service: sends prompt (evidence: `backend/app/services/llm_service.py`)
- Chat pipeline → Post-generation safety: checks draft (evidence: `backend/app/pipelines/chat.py`)
- Chat pipeline → Turn audit log: records turn (evidence: `backend/app/pipelines/chat.py`)
- Frontend API → Health endpoint: checks service status (evidence: `README.md`)
- Classifier training → Text normalization: uses preprocessing (evidence: `backend/app/training/risk_train.py`)
- Sentiment analysis → Text normalization: uses preprocessing (evidence: `backend/app/services/sentiment_service.py`)
- Emotion analysis → Text normalization: uses preprocessing (evidence: `backend/app/services/emotion_service.py`)
- Risk analysis → Text normalization: uses preprocessing (evidence: `backend/app/services/risk_service.py`)
- Chat endpoint → Chat interface: returns response
