# avyakta-dev/ai-therapist architecture

> Architecture diagram of the GitHub repository avyakta-dev/ai-therapist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avyakta-dev/ai-therapist
- Repository: https://github.com/avyakta-dev/ai-therapist

## Overview

##### What this project is (type + purpose)
This is a **2-tier full-stack web application**:

- **Frontend (SPA)**: React + TypeScript + Vite + Tailwind + shadcn/ui. It renders the “AI Therapist” chat UI and calls the backend over HTTP.
- **Backend (API service)**: FastAPI (Python) exposing endpoints (incl. `/health`) and acting as a **proxy/orchestrator** to an **external LLM provider** (Novita AI API, OpenAI-compatible).
- **External dependency**: Novita AI API for chat completions.
- **Deployment**: Split deployment: **Render** for backend, **Vercel** for frontend. `render.yaml` captures backend IaC.

- SPA → API calls → FastAPI → External LLM API
- Cross-origin, env var configuration (`VITE_API_BASE_URL`, `NOVITA_API_KEY`)
- Clear runtime boundaries: browser vs Vercel vs Render vs Novita

##### Top-level
- `backend/`: the FastAPI service.
- `frontend/`: the React/Vite SPA.
- `render.yaml`: backend deployment definition (Render).

##### Backend (key files)
- `backend/api.py`: likely the FastAPI `app` entrypoint (Render start command: `uvicorn api:app ...` confirms this).
- `backend/chatbot.py`: likely encapsulates the LLM prompt/logic and the Novita/OpenAI-compatible client calls.
- `backend/main.py`: potentially local runner / alternate entrypoint / composition.
- `backend/.env.example`: documents required env (`NOVITA_API_KEY`).

##### Frontend (key files)
- `frontend/src/pages/Chat.tsx`, `frontend/src/components/ChatInterface.tsx`, `frontend/src/components/AITherapist.tsx`: the “chat feature” UI and likely the API-calling component.
- `frontend/.env.example`: documents `VITE_API_BASE_URL` to locate the backend.
- `frontend/vercel.json`: deployment hints (routing, rewrites, etc.).
- `frontend/src/components/ui/*`: shadcn/ui component library wrappers—mostly UI, not a separate architectural service.

##### Vercel-hosted React SPA (Vite build)
- Key feature module: “Chat UI” (Chat page + ChatInterface + AITherapist)

##### Render-hosted FastAPI service
- FastAPI routes (in `api.py`) including `/health` and “chat” endpoint(s)
- Chat orchestration module (`chatbot.py`) that prepares messages/prompts and calls Novita

##### Novita AI API (OpenAI-compatible)
- Receives prompts/chat history and returns model responses

##### Environment Variables
- Frontend: `VITE_API_BASE_URL` (public config)
- Backend: `NOVITA_API_KEY` (secret)

##### Health/ops flow
- **Render Health Check → FastAPI `/health`**: liveness monitoring.

- “HTTPS (JSON)”
- “Chat messages / conversation context”
- “API key auth (server-side only)”
- “CORS (browser → API)”

##### Architectural patterns to highlight (specific to this repo)
1. **Backend-for-Frontend (BFF) / Proxy pattern**: FastAPI mediates LLM calls so the API key stays server-side.
2. **Stateless API (likely)**: No visible database; each request probably carries enough context (or the frontend carries chat history). If backend stores conversation in-memory, call that out as “ephemeral”.
##### Split deployment architecture
- Vercel: static SPA hosting + edge routing
- Render: containerized Python web service

##### External Providers (Novita)

Components inside the lane they run in. This alone prevents common inaccuracies (e.g., drawing React as “running on Vercel” vs “running in the browser”).

##### Decompose each tier into “as many components as possible” (without inventing things)
For this repo, a good level of decomposition is:

**Browser**
- Chat Page (`src/pages/Chat.tsx`)
- Chat components (`ChatInterface.tsx`, `AITherapist.tsx`)
- API client layer (where fetch/axios lives—locate in components or a lib file)

**FastAPI service**
- `api.py` (routes + app)
- `chatbot.py` (LLM integration / prompt building / API client)
- “Config” (env vars, settings)

**External**
- Novita AI API endpoint

- Browser ↔ SPA (Vercel) ↔ FastAPI (Render) ↔ Novita API
- Env vars + health check

- FastAPI app (`api.py`) → Chat module (`chatbot.py`) → Novita client
- Request/response DTOs conceptually (“chat request”, “chat response”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% High-level (C4 Container)
    %% =========================
    subgraph "High-level: Containers & Runtime Boundaries"
        direction TB

        subgraph "Client Runtime (Browser)"
            direction TB
            U(("User")):::actor
            B["Browser (renders SPA)"]:::client
            U -->|"uses"| B
        end

        subgraph "Frontend Hosting (Vercel)"
            direction TB
            VPLAT["Vercel Platform"]:::platform
            SPA["React SPA (Vite build → static assets)"]:::frontend
            VPLAT -->|"hosts"| SPA
        end

        subgraph "Backend Hosting (Render)"
            direction TB
            RPLAT["Render Platform"]:::platform
            API["FastAPI API Service"]:::backend
            RPLAT -->|"runs (uvicorn api:app)"| API
            HC["Render Health Check"]:::platform
            HC -->|"GET /health"| API
        end

        subgraph "External Provider"
            direction TB
            NOVITA["Novita AI API (OpenAI-compatible)"]:::external
        end

        subgraph "Configuration / Environment"
            direction TB
            FEENV["Frontend env: VITE_API_BASE_URL (public)"]:::config
            BEENV["Backend env: NOVITA_API_KEY (secret)"]:::secret
        end

        %% User + load
        B -->|"HTTPS GET static assets"| SPA

        %% SPA calls API via env-configured base URL
        FEENV -.->|"configures base URL"| SPA
        SPA -->|"HTTPS (JSON)\nCORS"| API

        %% Backend calls Novita using secret key
        BEENV -.->|"injects secret"| API
        API -->|"HTTPS (JSON)\nAPI key auth (server-side only)"| NOVITA
        NOVITA -->|"model response"| API
        API -->|"assistant message payload"| SPA
        SPA -->|"render UI updates"| B
    end

    %% =========================
    %% Mid-level: Frontend Components
    %% =========================
    subgraph "Frontend: SPA Components (Browser Runtime)"
        direction TB

        FE_MAIN["main.tsx (bootstraps React)"]:::frontend
        FE_APP["App.tsx (root shell / routing)"]:::frontend
        FE_CHAT["Chat.tsx (chat page)"]:::frontend
        FE_CI["ChatInterface.tsx (conversation UI + API calls)"]:::frontend
        FE_AIT["AITherapist.tsx (feature component)"]:::frontend
        FE_UI["shadcn/ui wrappers (components/ui/*)"]:::frontend
        FE_VITE["vite.config.ts (build tooling)"]:::build
        FE_VERCEL["vercel.json (deploy routing/rewrites)"]:::deploy
        FE_ENVFILE[".env.example (VITE_API_BASE_URL)"]:::config

        FE_MAIN -->|"renders"| FE_APP
        FE_APP -->|"routes to"| FE_CHAT
        FE_CHAT -->|"composes"| FE_CI
        FE_CI -->|"uses"| FE_AIT
        FE_CI -->|"uses"| FE_UI

        FE_ENVFILE -.->|"documents env"| FE_MAIN
        FE_VITE -.->|"build config"| FE_MAIN
        FE_VERCEL -.->|"deploy config"| SPA
    end

    %% =========================
    %% Mid-level: Backend Components
    %% =========================
    subgraph "Backend: FastAPI Components (Render Runtime)"
        direction TB

        BE_API["api.py (FastAPI app + routes)\n- /health\n- chat endpoint(s)"]:::backend
        BE_CHATBOT["chatbot.py (prompt/orchestration + Novita client)"]:::backend
        BE_MAIN["main.py (local runner / alternate entrypoint)"]:::backend
        BE_REQ["requirements.txt (deps)"]:::build
        BE_ENVFILE[".env.example (NOVITA_API_KEY)"]:::secret
        BE_RENDER["render.yaml (Render IaC/service config)"]:::deploy

        BE_API -->|"calls"| BE_CHATBOT
        BE_CHATBOT -->|"server-to-server HTTPS"| NOVITA

        BE_ENVFILE -.->|"documents secret"| BE_API
        BE_REQ -.->|"pins deps"| BE_API
        BE_RENDER -.->|"deploys"| API
        BE_MAIN -.->|"dev run option"| BE_API
    end

    %% Tie mid-level components to high-level containers
    SPA -.->|"serves bundle used by"| FE_MAIN
    API -.->|"implemented by"| BE_API

    %% Click events (from component_mapping)
    click BE_API "https://github.com/avyakta-dev/ai-therapist/blob/main/backend/api.py"
    click BE_CHATBOT "https://github.com/avyakta-dev/ai-therapist/blob/main/backend/chatbot.py"
    click BE_MAIN "https://github.com/avyakta-dev/ai-therapist/blob/main/backend/main.py"
    click BE_ENVFILE "https://github.com/avyakta-dev/ai-therapist/blob/main/backend/.env.example"
    click BE_REQ "https://github.com/avyakta-dev/ai-therapist/blob/main/backend/requirements.txt"
    click FE_MAIN "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/src/main.tsx"
    click FE_APP "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/src/App.tsx"
    click FE_CHAT "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/src/pages/Chat.tsx"
    click FE_CI "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/src/components/ChatInterface.tsx"
    click FE_AIT "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/src/components/AITherapist.tsx"
    click FE_UI "https://github.com/avyakta-dev/ai-therapist/tree/main/frontend/src/components/ui/"
    click FE_ENVFILE "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/.env.example"
    click FE_VERCEL "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/vercel.json"
    click FE_VITE "https://github.com/avyakta-dev/ai-therapist/blob/main/frontend/vite.config.ts"
    click BE_RENDER "https://github.com/avyakta-dev/ai-therapist/blob/main/render.yaml"

    %% Styles
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827
    classDef client fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0f172a
    classDef frontend fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#0f172a
    classDef backend fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#052e16
    classDef external fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#7c2d12
    classDef platform fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#111827
    classDef config fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#0f172a
    classDef secret fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d
    classDef deploy fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef build fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#2e1065
```
