# useriswild7099/zen architecture

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

- Interactive diagram: https://gitdiagram.com/useriswild7099/zen
- Repository: https://github.com/useriswild7099/zen

## Overview

Zen AI is a privacy-focused mental-wellness desktop/web application: users check in, chat with a specialized support persona, receive emotional or crisis guidance, and can use grounding exercises and a private journal. The frontend communicates with a stateless FastAPI backend for chat, analysis, navigation, translation, and optional score-only Sahayak triage; local Ollama supplies inference. Journal storage is client-side. The README documents capabilities beyond the sampled source, so those branches are shown at subsystem level without guessing internal call chains.

Main entry points: [`backend/main.py`](https://github.com/useriswild7099/zen/blob/main/backend/main.py) (FastAPI Entry), [`frontend/src/lib/api.ts`](https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/api.ts) (API Client), [`frontend/src/app/page.tsx`](https://github.com/useriswild7099/zen/blob/main/frontend/src/app/page.tsx) (Sanctuary UI), [`backend/routers/chat.py`](https://github.com/useriswild7099/zen/blob/main/backend/routers/chat.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Sanctuary"]
  node_app["Sanctuary UI<br/>[page.tsx]"]
  node_chat["Chat Support<br/>[ChatInterface.tsx]"]
  node_voice["Voice Input<br/>[useWhisper.ts]"]
  node_scrub["PII Scrubbing<br/>[privacy.ts]"]
  node_grounding["Grounding Tools"]
  node_journal["Journal Features"]
  node_vault[("Local Journal<br/>[storage.ts]")]
  node_api["API Client<br/>[api.ts]"]
end

subgraph group_backend["Support Services"]
  node_backend_app["FastAPI Entry<br/>[main.py]"]
  node_chat_route["Chat API<br/>[chat.py]"]
  node_sentiment_route["Sentiment API<br/>[sentiment.py]"]
  node_sia_route["Sia Navigator<br/>[sia.py]"]
  node_translate_route["Translation API<br/>[translate.py]"]
  node_journal_route["Journal API<br/>[journal.py]"]
  node_sahayak_route["Sahayak API<br/>[sahayak.py]"]
  node_nlp["Emotion Analysis<br/>[nlp_engine.py]"]
  node_crisis["Crisis Detection<br/>[crisis_detector.py]"]
  node_interventions["Care Interventions"]
  node_knowledge["Support Knowledge<br/>[knowledge_base.py]"]
  node_sahayak_sync["Score Sync<br/>[sahayak_sync.py]"]
end

subgraph group_inference["Local Inference"]
  node_ollama["Model Client<br/>[ollama_client.py]"]
end

subgraph group_reviewer["Sahayak Triage"]
  node_reviewer["Reviewer Portal"]
  node_score_store[("Anonymous Scores<br/>[sahayak.py]")]
end

node_user(("Person"))
node_ollama_service["Ollama"]

node_user -->|"uses"| node_app
node_app -->|"opens"| node_chat
node_app -->|"offers"| node_grounding
node_app -->|"opens"| node_journal
node_app -->|"requests"| node_api
node_chat -->|"captures speech"| node_voice
node_chat -->|"scrubs text"| node_scrub
node_scrub -->|"sends payload"| node_api
node_journal -->|"reads/writes"| node_vault
node_backend_app -->|"dispatches"| node_chat_route
node_backend_app -->|"dispatches"| node_sentiment_route
node_backend_app -->|"dispatches"| node_sia_route
node_backend_app -->|"dispatches"| node_translate_route
node_backend_app -->|"dispatches"| node_journal_route
node_backend_app -->|"dispatches"| node_sahayak_route
node_api -->|"calls"| node_chat_route
node_api -->|"calls"| node_sentiment_route
node_api -->|"calls"| node_sia_route
node_api -->|"calls"| node_translate_route
node_chat_route -->|"generates replies"| node_ollama
node_sentiment_route -->|"analyzes emotion"| node_nlp
node_sentiment_route -->|"checks risk"| node_crisis
node_sia_route -->|"finds resources"| node_knowledge
node_chat_route -->|"selects care"| node_interventions
node_ollama -->|"runs local models"| node_ollama_service
node_sahayak_route -->|"syncs scores"| node_sahayak_sync
node_sahayak_sync -->|"stores scores"| node_score_store
node_reviewer -.->|"reviews scores"| node_score_store

click node_app "https://github.com/useriswild7099/zen/blob/main/frontend/src/app/page.tsx"
click node_chat "https://github.com/useriswild7099/zen/blob/main/frontend/src/components/ChatInterface.tsx"
click node_voice "https://github.com/useriswild7099/zen/blob/main/frontend/src/hooks/useWhisper.ts"
click node_scrub "https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/privacy.ts"
click node_grounding "https://github.com/useriswild7099/zen/blob/main/frontend/src/components/BreathingExercise.tsx"
click node_journal "https://github.com/useriswild7099/zen/blob/main/frontend/src/components/EnhancedJournal.tsx"
click node_vault "https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/storage.ts"
click node_api "https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/api.ts"
click node_backend_app "https://github.com/useriswild7099/zen/blob/main/backend/main.py"
click node_chat_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/chat.py"
click node_sentiment_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/sentiment.py"
click node_sia_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/sia.py"
click node_translate_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/translate.py"
click node_journal_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/journal.py"
click node_sahayak_route "https://github.com/useriswild7099/zen/blob/main/backend/routers/sahayak.py"
click node_nlp "https://github.com/useriswild7099/zen/blob/main/backend/services/nlp_engine.py"
click node_crisis "https://github.com/useriswild7099/zen/blob/main/backend/services/crisis_detector.py"
click node_interventions "https://github.com/useriswild7099/zen/blob/main/backend/services/intervention_engine.py"
click node_knowledge "https://github.com/useriswild7099/zen/blob/main/backend/services/knowledge_base.py"
click node_sahayak_sync "https://github.com/useriswild7099/zen/blob/main/backend/services/sahayak_sync.py"
click node_ollama "https://github.com/useriswild7099/zen/blob/main/backend/services/ollama_client.py"
click node_score_store "https://github.com/useriswild7099/zen/blob/main/backend/routers/sahayak.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_app,node_chat,node_voice,node_scrub,node_grounding,node_journal,node_vault,node_api toneBlue
class node_backend_app,node_chat_route,node_sentiment_route,node_sia_route,node_translate_route,node_journal_route,node_sahayak_route,node_nlp,node_crisis,node_interventions,node_knowledge,node_sahayak_sync toneAmber
class node_ollama toneMint
class node_reviewer,node_score_store toneRose
class node_user,node_ollama_service toneIndigo
```

## Components

### User Sanctuary

- [Sanctuary UI](https://github.com/useriswild7099/zen/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Chat Support](https://github.com/useriswild7099/zen/blob/main/frontend/src/components/ChatInterface.tsx): `frontend/src/components/ChatInterface.tsx`
- [Voice Input](https://github.com/useriswild7099/zen/blob/main/frontend/src/hooks/useWhisper.ts): `frontend/src/hooks/useWhisper.ts`
- [PII Scrubbing](https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/privacy.ts): `frontend/src/lib/privacy.ts`
- [Grounding Tools](https://github.com/useriswild7099/zen/blob/main/frontend/src/components/BreathingExercise.tsx): `frontend/src/components/BreathingExercise.tsx`
- [Journal Features](https://github.com/useriswild7099/zen/blob/main/frontend/src/components/EnhancedJournal.tsx): `frontend/src/components/EnhancedJournal.tsx`
- [Local Journal](https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/storage.ts): `frontend/src/lib/storage.ts`
- [API Client](https://github.com/useriswild7099/zen/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Support Services

- [FastAPI Entry](https://github.com/useriswild7099/zen/blob/main/backend/main.py): `backend/main.py`
- [Chat API](https://github.com/useriswild7099/zen/blob/main/backend/routers/chat.py): `backend/routers/chat.py`
- [Sentiment API](https://github.com/useriswild7099/zen/blob/main/backend/routers/sentiment.py): `backend/routers/sentiment.py`
- [Sia Navigator](https://github.com/useriswild7099/zen/blob/main/backend/routers/sia.py): `backend/routers/sia.py`
- [Translation API](https://github.com/useriswild7099/zen/blob/main/backend/routers/translate.py): `backend/routers/translate.py`
- [Journal API](https://github.com/useriswild7099/zen/blob/main/backend/routers/journal.py): `backend/routers/journal.py`
- [Sahayak API](https://github.com/useriswild7099/zen/blob/main/backend/routers/sahayak.py): `backend/routers/sahayak.py`
- [Emotion Analysis](https://github.com/useriswild7099/zen/blob/main/backend/services/nlp_engine.py): `backend/services/nlp_engine.py`
- [Crisis Detection](https://github.com/useriswild7099/zen/blob/main/backend/services/crisis_detector.py): `backend/services/crisis_detector.py`
- [Care Interventions](https://github.com/useriswild7099/zen/blob/main/backend/services/intervention_engine.py): `backend/services/intervention_engine.py`
- [Support Knowledge](https://github.com/useriswild7099/zen/blob/main/backend/services/knowledge_base.py): `backend/services/knowledge_base.py`
- [Score Sync](https://github.com/useriswild7099/zen/blob/main/backend/services/sahayak_sync.py): `backend/services/sahayak_sync.py`

### Local Inference

- [Model Client](https://github.com/useriswild7099/zen/blob/main/backend/services/ollama_client.py): `backend/services/ollama_client.py`

### Sahayak Triage

- **Reviewer Portal**
- [Anonymous Scores](https://github.com/useriswild7099/zen/blob/main/backend/routers/sahayak.py): `backend/routers/sahayak.py`

### Other components

- **Person**
- **Ollama**

## Connections

- Person → Sanctuary UI: uses
- Sanctuary UI → Chat Support: opens
- Sanctuary UI → Grounding Tools: offers
- Sanctuary UI → Journal Features: opens
- Sanctuary UI → API Client: requests
- Chat Support → Voice Input: captures speech
- Chat Support → PII Scrubbing: scrubs text
- PII Scrubbing → API Client: sends payload
- Journal Features → Local Journal: reads/writes
- FastAPI Entry → Chat API: dispatches
- FastAPI Entry → Sentiment API: dispatches
- FastAPI Entry → Sia Navigator: dispatches
- FastAPI Entry → Translation API: dispatches
- FastAPI Entry → Journal API: dispatches
- FastAPI Entry → Sahayak API: dispatches
- API Client → Chat API: calls
- API Client → Sentiment API: calls
- API Client → Sia Navigator: calls
- API Client → Translation API: calls
- Chat API → Model Client: generates replies
- Sentiment API → Emotion Analysis: analyzes emotion
- Sentiment API → Crisis Detection: checks risk
- Sia Navigator → Support Knowledge: finds resources
- Chat API → Care Interventions: selects care
- Model Client → Ollama: runs local models
- Sahayak API → Score Sync: syncs scores
- Score Sync → Anonymous Scores: stores scores
- Reviewer Portal → Anonymous Scores: reviews scores