How erokhinvi/socrates works
Project Type and Purpose
• This is a full‑stack, AI‑powered interview practice application.
• Frontend: static HTML/CSS pages (index, interview, evaluation, etc.).
• Backend: FastAPI REST service orchestrating agents that call OpenAI (and local STT/TTS modules).
File Structure
• Top level:
• main.py (entry point for Uvicorn + FastAPI)
• config/nginx‑fastapi.conf (reverse proxy config)
• setup.sh, dev.sh, .github/workflows (CI/CD & deployment scripts)
• app/api: defines HTTP endpoints (evaluation.py, interview.py, field_description.py).
• app/agents: core “agent” classes (interviewee, evaluation, field_description), prompts (YAML) and extraction tools.
• app/core: configuration & OpenAI client wrapper.
• app/model: stt/tts/ttt modules for speech/text processing.
• app/frontend/static + HTML files: user interface.
• app/utils: shared utilities.
README
• Confirms tech stack: Python, FastAPI, Uvicorn, OpenAI Agent SDK.
• Provides deployment flow: GitHub Actions → DigitalOcean droplet → Nginx + Uvicorn.
Main Components & Interactions
a. Components
• User’s Browser (UI)
• Frontend Static Assets (HTML/CSS/JS)
• Nginx Reverse Proxy
• Uvicorn FastAPI Application
– API Layer (app/api/*)
– Agent Layer (app/agents/*)
– Model Layer (app/model/*)
– Core Layer (config, OpenAI client)
• External Services:
– OpenAI API
– (Optionally) local or third‑party STT/TTS engines
• CI/CD (GitHub Actions) and Deployment Scripts
b. Relationships & Data Flow
1. User → Browser → Requests HTML pages & static assets (GET)
2. Browser → API endpoints (POST /interview, /evaluation, /field_description)
3. FastAPI routes invoke corresponding Agent classes.
4. Agent uses prompts & tools to format a request.
5. Agent calls OpenAI via core/openai.py (and local stt/tts modules for audio).
6. OpenAI responds → Agent processes result → returns JSON to frontend.
7. Browser renders results or report page.
8. CI/CD pipeline pushes code → GitHub Actions → DigitalOcean droplet → Nginx + Uvicorn.
c. Architectural Patterns & Principles
• Layered architecture:
UI Layer ←→ API Layer ←→ Service/Agent Layer ←→ External API Layer
• Single‑process monolith served by Uvicorn behind Nginx
• Clear separation of concerns: prompts vs tools vs agents vs API vs core config.
• Configuration via environment (.env) and core/config.py.
d. Key Technologies & Frameworks
• Python 3.x
• FastAPI + Uvicorn
• OpenAI Agent SDK
• HTML/CSS (no JS framework) for frontend
• Nginx as reverse proxy
• GitHub Actions for CI/CD
• DigitalOcean droplet as runtime environment
High‑Detail Capture
• YAML prompt store as a resource feeding into the Agent layer.