How oliver-lack/chatpsych works
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.