# mukesh360/psychtrend architecture

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

- Interactive diagram: https://gitdiagram.com/mukesh360/psychtrend
- Repository: https://github.com/mukesh360/psychtrend

## Overview

Psychological Trend Analysis System is a local-first behavioral reflection chatbot. A user starts a session in the chat UI, answers adaptive questions, and receives a report after responses are structured, stored, and analyzed for sentiment, trends, behavioral archetypes, and predictions. The report UI presents those results; optional Ollama enhancements normalize input and humanize explanations without replacing statistical analysis. The graph combines sampled source relationships with documented capabilities and workflow; links based only on documentation are cited to the README.

Main entry points: [`backend/main.py`](https://github.com/mukesh360/psychtrend/blob/main/backend/main.py) (FastAPI routes), [`backend/llm_service.py`](https://github.com/mukesh360/psychtrend/blob/main/backend/llm_service.py) (LLM enhancements), [`frontend/js/chat.js`](https://github.com/mukesh360/psychtrend/blob/main/frontend/js/chat.js) (Chat UI), [`backend/chat_logic.py`](https://github.com/mukesh360/psychtrend/blob/main/backend/chat_logic.py) (Adaptive questions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat_ui["Chat UI<br/>[chat.js]"]
  node_chat_page["Chat page<br/>[index.html]"]
  node_report_ui["Report UI<br/>[report.js]"]
  node_report_page["Report page<br/>[report.html]"]
end

subgraph group_orchestration["Conversation and API"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_question_flow["Adaptive questions<br/>[chat_logic.py]"]
  node_question_bank["Question bank<br/>[questions.json]"]
  node_response_processing["Response structuring<br/>[data_processor.py]"]
  node_data_models["API data models<br/>[models.py]"]
end

subgraph group_analysis["Behavioral analysis"]
  node_sentiment["Sentiment analysis<br/>[sentiment.py]"]
  node_trend_analysis["Trend analysis<br/>[trends.py]"]
  node_sentiment_context["Sentiment safeguards"]
  node_archetypes["Behavioral clustering<br/>[clustering.py]"]
  node_predictions["Behavior predictions<br/>[predictor.py]"]
end

subgraph group_reporting["Reports and language"]
  node_report_generation["Report generation<br/>[main.py]"]
  node_llm_service["LLM enhancements<br/>[llm_service.py]"]
  node_prompts["LLM prompts<br/>[llm_prompts.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
end

subgraph group_persistence["Local persistence"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_user(("User"))
node_ollama(("Ollama service"))

node_user -->|"answers questions"| node_chat_ui
node_chat_page -->|"hosts interface"| node_chat_ui
node_chat_ui -->|"sends messages"| node_api
node_api -->|"returns responses"| node_chat_ui
node_api -->|"validates requests"| node_data_models
node_api -->|"advances conversation"| node_question_flow
node_question_flow -.->|"selects questions"| node_question_bank
node_api -->|"structures responses"| node_response_processing
node_api -->|"reads and writes sessions"| node_database
node_api -->|"analyzes responses"| node_sentiment
node_api -->|"computes trends"| node_trend_analysis
node_api -->|"clusters behavior"| node_archetypes
node_api -->|"computes predictions"| node_predictions
node_trend_analysis -->|"applies score caps"| node_sentiment_context
node_archetypes -->|"filters archetypes"| node_sentiment_context
node_api -->|"formats report"| node_report_generation
node_report_generation -->|"stores report"| node_database
node_report_generation -->|"serves report data"| node_report_ui
node_report_page -->|"hosts report view"| node_report_ui
node_report_ui -->|"displays insights"| node_user
node_question_flow -->|"enhances questions"| node_llm_service
node_response_processing -->|"normalizes input"| node_llm_service
node_llm_service -->|"uses templates"| node_prompts
node_llm_service -->|"requests generation"| node_ollama_client
node_ollama_client -->|"calls local model"| node_ollama

click node_chat_ui "https://github.com/mukesh360/psychtrend/blob/main/frontend/js/chat.js"
click node_chat_page "https://github.com/mukesh360/psychtrend/blob/main/frontend/index.html"
click node_report_ui "https://github.com/mukesh360/psychtrend/blob/main/frontend/js/report.js"
click node_report_page "https://github.com/mukesh360/psychtrend/blob/main/frontend/report.html"
click node_api "https://github.com/mukesh360/psychtrend/blob/main/backend/main.py"
click node_question_flow "https://github.com/mukesh360/psychtrend/blob/main/backend/chat_logic.py"
click node_question_bank "https://github.com/mukesh360/psychtrend/blob/main/data/questions.json"
click node_response_processing "https://github.com/mukesh360/psychtrend/blob/main/backend/data_processor.py"
click node_data_models "https://github.com/mukesh360/psychtrend/blob/main/backend/models.py"
click node_sentiment "https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/sentiment.py"
click node_trend_analysis "https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/trends.py"
click node_sentiment_context "https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/sentiment_context.py"
click node_archetypes "https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/clustering.py"
click node_predictions "https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/predictor.py"
click node_report_generation "https://github.com/mukesh360/psychtrend/blob/main/backend/main.py"
click node_llm_service "https://github.com/mukesh360/psychtrend/blob/main/backend/llm_service.py"
click node_prompts "https://github.com/mukesh360/psychtrend/blob/main/backend/llm_prompts.py"
click node_ollama_client "https://github.com/mukesh360/psychtrend/blob/main/backend/ollama_client.py"
click node_database "https://github.com/mukesh360/psychtrend/blob/main/backend/database.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_chat_ui,node_chat_page,node_report_ui,node_report_page,node_user toneBlue
class node_api,node_question_flow,node_question_bank,node_response_processing,node_data_models toneAmber
class node_sentiment,node_trend_analysis,node_sentiment_context,node_archetypes,node_predictions toneMint
class node_report_generation,node_llm_service,node_prompts,node_ollama_client toneRose
class node_database,node_ollama toneIndigo
```

## Components

### User experience

- [Chat UI](https://github.com/mukesh360/psychtrend/blob/main/frontend/js/chat.js): `frontend/js/chat.js`
- [Chat page](https://github.com/mukesh360/psychtrend/blob/main/frontend/index.html): `frontend/index.html`
- [Report UI](https://github.com/mukesh360/psychtrend/blob/main/frontend/js/report.js): `frontend/js/report.js`
- [Report page](https://github.com/mukesh360/psychtrend/blob/main/frontend/report.html): `frontend/report.html`

### Conversation and API

- [FastAPI routes](https://github.com/mukesh360/psychtrend/blob/main/backend/main.py): `backend/main.py`
- [Adaptive questions](https://github.com/mukesh360/psychtrend/blob/main/backend/chat_logic.py): `backend/chat_logic.py`
- [Question bank](https://github.com/mukesh360/psychtrend/blob/main/data/questions.json): `data/questions.json`
- [Response structuring](https://github.com/mukesh360/psychtrend/blob/main/backend/data_processor.py): `backend/data_processor.py`
- [API data models](https://github.com/mukesh360/psychtrend/blob/main/backend/models.py): `backend/models.py`

### Behavioral analysis

- [Sentiment analysis](https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/sentiment.py): `backend/ml_engine/sentiment.py`
- [Trend analysis](https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/trends.py): `backend/ml_engine/trends.py`
- [Sentiment safeguards](https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/sentiment_context.py): `backend/ml_engine/sentiment_context.py`
- [Behavioral clustering](https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/clustering.py): `backend/ml_engine/clustering.py`
- [Behavior predictions](https://github.com/mukesh360/psychtrend/blob/main/backend/ml_engine/predictor.py): `backend/ml_engine/predictor.py`

### Reports and language

- [Report generation](https://github.com/mukesh360/psychtrend/blob/main/backend/main.py): `backend/main.py`
- [LLM enhancements](https://github.com/mukesh360/psychtrend/blob/main/backend/llm_service.py): `backend/llm_service.py`
- [LLM prompts](https://github.com/mukesh360/psychtrend/blob/main/backend/llm_prompts.py): `backend/llm_prompts.py`
- [Ollama client](https://github.com/mukesh360/psychtrend/blob/main/backend/ollama_client.py): `backend/ollama_client.py`

### Local persistence

- [SQLite database](https://github.com/mukesh360/psychtrend/blob/main/backend/database.py): `backend/database.py`

### Other components

- **User**
- **Ollama service**

## Connections

- User → Chat UI: answers questions (evidence: `README.md`)
- Chat page → Chat UI: hosts interface (evidence: `README.md`)
- Chat UI → FastAPI routes: sends messages (evidence: `README.md`)
- FastAPI routes → Chat UI: returns responses (evidence: `README.md`)
- FastAPI routes → API data models: validates requests (evidence: `backend/main.py`)
- FastAPI routes → Adaptive questions: advances conversation (evidence: `backend/main.py`)
- Adaptive questions → Question bank: selects questions (evidence: `README.md`)
- FastAPI routes → Response structuring: structures responses (evidence: `backend/main.py`)
- FastAPI routes → SQLite database: reads and writes sessions (evidence: `backend/main.py`)
- FastAPI routes → Sentiment analysis: analyzes responses (evidence: `backend/main.py`)
- FastAPI routes → Trend analysis: computes trends (evidence: `backend/main.py`)
- FastAPI routes → Behavioral clustering: clusters behavior (evidence: `backend/main.py`)
- FastAPI routes → Behavior predictions: computes predictions (evidence: `backend/main.py`)
- Trend analysis → Sentiment safeguards: applies score caps (evidence: `backend/ml_engine/trends.py`)
- Behavioral clustering → Sentiment safeguards: filters archetypes (evidence: `backend/ml_engine/clustering.py`)
- FastAPI routes → Report generation: formats report (evidence: `README.md`)
- Report generation → SQLite database: stores report (evidence: `backend/database.py`)
- Report generation → Report UI: serves report data (evidence: `README.md`)
- Report page → Report UI: hosts report view (evidence: `README.md`)
- Report UI → User: displays insights (evidence: `README.md`)
- Adaptive questions → LLM enhancements: enhances questions (evidence: `backend/chat_logic.py`)
- Response structuring → LLM enhancements: normalizes input (evidence: `backend/data_processor.py`)
- LLM enhancements → LLM prompts: uses templates (evidence: `backend/llm_service.py`)
- LLM enhancements → Ollama client: requests generation (evidence: `backend/llm_service.py`)
- Ollama client → Ollama service: calls local model (evidence: `backend/ollama_client.py`)
