dk-krishna2001/trisoul-ai

1. What this repo is

Trisoul AI is an academic mental-health support prototype with a clear split between a browser client and a Python API. The backend is the system of record for conversation state, mood tracking, retrieval, and agent orchestration; the frontend is mostly presentation, chat interaction, and dashboard rendering.

2. Frontend boundary

The frontend/ app is a static browser UI built from index.html, script.js, auth.js, and style.css. It handles user sign-in, chat input/output, session navigation, and mood/summary displays. It also has a benchmark-login path that uses a shared password instead of normal user auth.

3. Backend API boundary

backend/main.py is the orchestration layer exposed through FastAPI. It serves the live chat endpoints, user/session read endpoints, benchmark endpoints, and the transcription path mentioned in the README. This layer is stateless in memory and relies on external stores for session history and mood analytics.

4. Agent workflow core

backend/ai_agent.py contains the main LangGraph StateGraph-based conversational workflow. The key architectural choice is a parallel reasoning path: a clinical branch and a sentiment branch run concurrently, then feed a synthesis step. That synthesis output is passed through a response guard/rewrite layer before being returned.

5. Routing and safety behavior

The first agent step is a router that decides whether a message is ordinary therapy support, an emergency-like message, or a therapist-location request. Emergency and location requests bypass the normal therapy synthesis path and are handled by dedicated flows. This makes safety and “find a therapist” behavior separate from the reflective chat pipeline.

6. Streaming response path

The /ask path is designed for streamed delivery rather than a single final response. The backend saves the user message, performs intent routing, then streams token chunks from the synthesis stage back to the browser while the response is still being generated. This is the main latency/UX optimization in the system.

7. Persistence layer

backend/firebase_db.py is the persistence boundary for chat sessions, messages, and mood data. The README indicates Firebase/Firestore is used for user-scoped storage, with separate session histories per user and read endpoints for sessions, messages, and mood trends. The architecture treats this as durable application state outside the API process.

8. Memory and personalization

backend/memory.py provides semantic retrieval from ChromaDB, used to pull relevant past context into the agent prompt. That sits alongside session history: session data preserves the conversation record, while memory retrieval supplies longer-range personalization across sessions. This is what lets replies reference prior themes without loading the entire history every time.

9. Tools and external integrations

backend/tools.py is the integration layer for non-LLM actions such as emergency workflows, therapist-location lookup, and other helper tools referenced in the README. The system depends on external services where needed: Firebase for auth/storage, Groq/OpenAI for model calls, Google Maps for clinic search, and Twilio for emergency-related tooling.

10. Benchmarking and evaluation

The repo includes explicit academic evaluation support: /testbench/ask, /testbench/login, and /testbench/therapist/chats for benchmark users and therapist-style exports. backend/run_trisoul_evaluation.py and related scripts automate live evaluation against a running API and write results to ignored output files. This makes evaluation a first-class subsystem, not an afterthought.

11. Configuration and deployment

backend/config.py, .env.example, and the Firebase credential file define runtime configuration and secrets boundaries. In production, the README says Nginx serves the static frontend and reverse-proxies API traffic to the FastAPI backend, while systemd keeps the backend process alive and Let’s Encrypt provides TLS. So deployment is a classic static-web-plus-API topology, not a single monolith.

12. How the main data flows connect

A typical user message flows from browser UI to FastAPI, then into storage, retrieval, routing, parallel agent analysis, synthesis, and response streaming back to the browser. The final AI message is persisted to Firebase, and mood/session data can then be read back for analytics views. Benchmark flows follow the same backend patterns but use isolated benchmark identities and export endpoints.