# oliver-lack/chatpsych architecture

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

- Interactive diagram: https://gitdiagram.com/oliver-lack/chatpsych
- Repository: https://github.com/oliver-lack/chatpsych

## Overview

##### Project type and purpose
- chatPsych is a full-stack experimental web application built with Flask (Python) and Gunicorn.
- It serves as an AI interface for human-AI interaction research, integrating multiple LLM APIs, collecting detailed interaction data, and providing a researcher dashboard.

##### File structure analysis
- Top-level Python modules and scripts: API_LLM.py, chatPsych.py, audio_API/API_audio.py
- Configuration and deployment artifacts: Dockerfile, docker-compose.yml, Procfile, .env.example, DEPLOYMENT_*.md
- Agent definitions: agents/default.json
- Static assets: static/css (styles.css), static/js (chat.js, pre_survey.js, post_survey.js, research_dashboard.js), static/images, static/uploads
- Templates: Jinja2 HTML files under templates/ (chat.html, login.html, survey pages, dashboard)
- Database: users.db (SQLite) managed via SQLAlchemy or direct SQLite
- Requirements and environment: requirements.txt, .gitignore, .dockerIgnore, .vscode/

##### README insights
- Highlights the Flask + Gunicorn web server, SQLite database, multi-model API integration (OpenAI, Anthropic, Google Gemini, etc.), agent JSON configurations, experimental condition management, data logging, researcher dashboard, and audio support.
- Emphasizes deployment on AWS with Docker, Apache2, SSL/TLS, and environment variable management.

##### Main components
a. Web Application Layer
- Flask app (chatPsych.py) behind Gunicorn WSGI server
- Static file server (CSS, JS, images under /static)
- Jinja2 template engine serving HTML pages (/templates)
b. Data Layer
- SQLite database (users.db) with Users, Messages, Passwords tables
- Interaction logs (interactions.json, interactions_backup.csv) stored on disk
c. API Integration Layer
- External LLM services (OpenAI, Anthropic, Google, etc.) via API_LLM.py and audio_API/API_audio.py
- LiteLLM abstraction and fallback logic
d. Researcher Dashboard
- Flask-based GUI for managing agents, conditions, timers, data downloads
e. Agents Configuration
- JSON files in agents/ (default.json) defining system prompts and parameters
f. Deployment & Infrastructure
- Docker container, docker-compose for local or multi-service setup
- Procfile for Heroku, Apache2 + Gunicorn on AWS EC2, SSL/TLS via Certbot

##### Relationships and interactions
- Client browser ⇄ Flask/Gunicorn (HTTPS)
- Flask retrieves templates and static assets, manages sessions/cookies
- Flask reads/writes SQLite and log files
- Flask invokes API_LLM.py / API_audio.py → External LLM endpoints
- Researcher Dashboard components interact with the same Flask backend and DB
- Deployment artifacts wrap the entire Flask app in Docker or cloud VM

##### Architectural patterns & design principles
- MVC-like separation:
- Model = SQLite + log files
- View = Jinja2 templates + static assets
- Controller = Flask routes in chatPsych.py
- Strategy pattern via JSON-based agent configuration
- Adapter/facade pattern for multi-LLM API abstraction (LiteLLM)
- Single-page dynamic interactions via AJAX calls in chat.js
- Modular separation: audio vs text API modules

##### Final advice
- Incorporate logos next to each component to visually denote its file format or technology.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend (Client)" 
        direction TB
        ChatHTML["Chat Interface<br/>templates/chat.html"]:::template
        LoginHTML["Login Page<br/>templates/login.html"]:::template
        PreSurveyHTML["Pre-Survey Page<br/>templates/pre_survey.html"]:::template
        PostSurveyHTML["Post-Survey Page<br/>templates/post_survey.html"]:::template
        SurveyHTML["Survey Page<br/>templates/survey.html"]:::template
        DashboardHTML["Researcher Dashboard<br/>templates/research_dashboard.html"]:::template

        CSS["styles.css"]:::css
        ChatJS["chat.js"]:::js
        PreSurveyJS["pre_survey.js"]:::js
        PostSurveyJS["post_survey.js"]:::js
        DashboardJS["research_dashboard.js"]:::js
        Images["Images & Uploads<br/>static/images/, static/uploads/"]:::assets
    end

    %% Deployment Boundary
    subgraph "Deployment Container<br/>(Docker / EC2)" 
        classDef container fill:#f0f8ff,stroke:#333,stroke-width:2px
        direction TB
        subgraph "Backend (Server)" 
            direction TB
            FlaskApp["chatPsych.py"]:::python
            Gunicorn["Gunicorn WSGI (Procfile)"]:::config
            Env[".env.example"]:::config
            DockerCfg["Dockerfile"]:::config
            DockerCompose["docker-compose.yml"]:::config
            DeployLocal["DEPLOYMENT_local.md"]:::config
            DeployExt["DEPLOYMENT_online_extensive.md"]:::config
            DeploySimple["DEPLOYMENT_online_simple.md"]:::config
            Requirements["requirements.txt"]:::config
            Gitignore[".gitignore, .dockerIgnore"]:::config
            VSCode[".vscode/"]:::config

            API_LLM["API_LLM.py"]:::python
            AudioAPI["API_audio.py"]:::python
            AgentsJSON["default.json<br/>agents/"]:::json

            %% Repository structure nodes
        end

        subgraph "Data Store" 
            direction TB
            SQLiteDB["SQLite (users.db)"]:::database
            Logs["Interaction Logs<br/>.json, .csv"]:::data
        end
    end

    %% External Services
    subgraph "External LLM Services" 
        direction TB
        OpenAI["OpenAI"]:::external
        Anthropic["Anthropic"]:::external
        GoogleGemini["Google Gemini"]:::external
        Fallback["LiteLLM Fallback"]:::external
    end

    %% Relationships
    User -->|HTTP GET/POST| ChatHTML
    User -->|HTTP GET/POST| LoginHTML
    User -->|HTTP GET/POST| PreSurveyHTML
    User -->|HTTP GET/POST| PostSurveyHTML
    User -->|HTTP GET/POST| SurveyHTML
    User -->|HTTP GET/POST| DashboardHTML

    ChatHTML -->|loads| CSS
    ChatHTML -->|loads| ChatJS
    PreSurveyHTML -->|loads| CSS
    PreSurveyHTML -->|loads| PreSurveyJS
    PostSurveyHTML -->|loads| CSS
    PostSurveyHTML -->|loads| PostSurveyJS
    DashboardHTML -->|loads| CSS
    DashboardHTML -->|loads| DashboardJS
    ChatHTML -->|loads| Images
    DashboardHTML -->|loads| Images

    ChatJS -->|AJAX JSON| FlaskApp
    PreSurveyJS -->|AJAX JSON| FlaskApp
    PostSurveyJS -->|AJAX JSON| FlaskApp
    DashboardJS -->|AJAX JSON| FlaskApp

    FlaskApp -->|spawns| Gunicorn
    Gunicorn -->|uses| DockerCfg
    Gunicorn -->|uses| Env

    FlaskApp -->|reads/writes| SQLiteDB
    FlaskApp -->|appends| Logs
    FlaskApp -->|loads| AgentsJSON

    FlaskApp -->|calls| API_LLM
    FlaskApp -->|calls| AudioAPI

    API_LLM -->|HTTP| OpenAI
    API_LLM -->|HTTP| Anthropic
    API_LLM -->|HTTP| GoogleGemini
    API_LLM -->|fallback logic| Fallback

    AudioAPI -->|HTTP| OpenAI
    AudioAPI -->|HTTP| Anthropic

    %% Click Events
    click FlaskApp "https://github.com/oliver-lack/chatpsych/blob/main/chatPsych.py"
    click Gunicorn "https://github.com/oliver-lack/chatpsych/tree/main/Procfile"
    click DockerCfg "https://github.com/oliver-lack/chatpsych/tree/main/Dockerfile"
    click DockerCompose "https://github.com/oliver-lack/chatpsych/blob/main/docker-compose.yml"
    click Env "https://github.com/oliver-lack/chatpsych/blob/main/.env.example"
    click DeployLocal "https://github.com/oliver-lack/chatpsych/blob/main/DEPLOYMENT_local.md"
    click DeployExt "https://github.com/oliver-lack/chatpsych/blob/main/DEPLOYMENT_online_extensive.md"
    click DeploySimple "https://github.com/oliver-lack/chatpsych/blob/main/DEPLOYMENT_online_simple.md"
    click Requirements "https://github.com/oliver-lack/chatpsych/blob/main/requirements.txt"
    click Gitignore "https://github.com/oliver-lack/chatpsych/blob/main/.gitignore"
    click Gitignore "https://github.com/oliver-lack/chatpsych/blob/main/.dockerIgnore"
    click VSCode "https://github.com/oliver-lack/chatpsych/blob/main/.vscode"
    click API_LLM "https://github.com/oliver-lack/chatpsych/blob/main/API_LLM.py"
    click AudioAPI "https://github.com/oliver-lack/chatpsych/blob/main/audio_API/API_audio.py"
    click AgentsJSON "https://github.com/oliver-lack/chatpsych/blob/main/agents/default.json"
    click CSS "https://github.com/oliver-lack/chatpsych/blob/main/static/css/styles.css"
    click ChatJS "https://github.com/oliver-lack/chatpsych/blob/main/static/js/chat.js"
    click PreSurveyJS "https://github.com/oliver-lack/chatpsych/blob/main/static/js/pre_survey.js"
    click PostSurveyJS "https://github.com/oliver-lack/chatpsych/blob/main/static/js/post_survey.js"
    click DashboardJS "https://github.com/oliver-lack/chatpsych/blob/main/static/js/research_dashboard.js"
    click Images "https://github.com/oliver-lack/chatpsych/tree/main/static/images/"
    click Images "https://github.com/oliver-lack/chatpsych/tree/main/static/uploads/"
    click ChatHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/chat.html"
    click LoginHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/login.html"
    click PreSurveyHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/pre_survey.html"
    click PostSurveyHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/post_survey.html"
    click SurveyHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/survey.html"
    click DashboardHTML "https://github.com/oliver-lack/chatpsych/blob/main/templates/research_dashboard.html"

    %% Styles
    classDef user fill:#ffd700,stroke:#333,stroke-width:1px
    classDef frontend fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef template fill:#fafad2,stroke:#333,stroke-width:1px
    classDef css fill:#98fb98,stroke:#333,stroke-width:1px
    classDef js fill:#add8e6,stroke:#333,stroke-width:1px
    classDef assets fill:#d8bfd8,stroke:#333,stroke-width:1px
    classDef container fill:none,stroke:#000,stroke-width:2px
    classDef python fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef config fill:#f5deb3,stroke:#333,stroke-width:1px
    classDef json fill:#ffebcd,stroke:#333,stroke-width:1px
    classDef database fill:#deb887,stroke:#333,stroke-width:1px
    classDef data fill:#ffdead,stroke:#333,stroke-width:1px
    classDef external fill:#e6e6fa,stroke:#333,stroke-width:1px
```
