# erokhinvi/socrates architecture

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

- Interactive diagram: https://gitdiagram.com/erokhinvi/socrates
- Repository: https://github.com/erokhinvi/socrates

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend Layer"
        Browser["User’s Browser"]:::frontend
        Static["Frontend Static Assets"]:::frontend
    end

    subgraph "Backend Layer"
        Nginx["Nginx Reverse Proxy (80/443→8000)"]:::backend
        Uvicorn["Uvicorn + FastAPI (app/main.py)"]:::backend

        subgraph "API Layer"
            InterviewAPI["Interview API"]:::api
            EvalAPI["Evaluation API"]:::api
            FieldDescAPI["Field Description API"]:::api
        end

        subgraph "Agent Layer"
            InterviewAgent["Interviewee Agent"]:::agent
            EvalAgent["Evaluation Agent"]:::agent
            FieldAgent["Field Description Agent"]:::agent

            subgraph "Prompts"
                Prompts["YAML Prompt Store"]:::storage
            end

            subgraph "Tools"
                ExtractTools["Extraction Tools"]:::tools
            end
        end

        subgraph "Model Layer"
            STT["STT Module"]:::model
            TTS["TTS Module"]:::model
            TTT["Text‐Text Module"]:::model
        end

        subgraph "Core Layer"
            Config["Config & Constants"]:::core
            OpenAI["OpenAI Client"]:::core
        end

        Shared["Shared Utilities"]:::core
    end

    subgraph "External Services"
        OA["OpenAI API"]:::external
        Speech["Local/Third‑party STT/TTS"]:::external
    end

    subgraph "CI/CD & Deployment"
        GH["GitHub Actions"]:::ci
        DO["DigitalOcean Droplet"]:::ci
        Scripts["Deployment Scripts"]:::ci
    end

    Browser --> Static
    Browser -->|HTTP GET| Nginx
    Nginx -->|Proxy HTTP| Uvicorn
    Uvicorn --> InterviewAPI
    Uvicorn --> EvalAPI
    Uvicorn --> FieldDescAPI

    InterviewAPI --> InterviewAgent
    EvalAPI --> EvalAgent
    FieldDescAPI --> FieldAgent

    InterviewAgent --> Prompts
    InterviewAgent --> ExtractTools
    EvalAgent --> Prompts
    EvalAgent --> ExtractTools
    FieldAgent --> Prompts
    FieldAgent --> ExtractTools

    InterviewAgent --> OpenAI
    EvalAgent --> OpenAI
    FieldAgent --> OpenAI

    InterviewAgent --> STT
    InterviewAgent --> TTS
    InterviewAgent --> TTT
    EvalAgent --> STT
    EvalAgent --> TTS
    EvalAgent --> TTT
    FieldAgent --> STT
    FieldAgent --> TTS
    FieldAgent --> TTT

    OpenAI --> OA
    Config --> OpenAI
    Shared --> InterviewAPI
    Shared --> EvalAPI
    Shared --> FieldDescAPI

    GH --> DO
    DO --> Nginx
    DO --> Uvicorn
    Scripts --> DO

    click Static "https://github.com/erokhinvi/socrates/tree/main/app/frontend"
    click Nginx "https://github.com/erokhinvi/socrates/blob/main/config/nginx-fastapi.conf"
    click Uvicorn "https://github.com/erokhinvi/socrates/blob/main/app/main.py"
    click InterviewAPI "https://github.com/erokhinvi/socrates/blob/main/app/api/interview.py"
    click EvalAPI "https://github.com/erokhinvi/socrates/blob/main/app/api/evaluation.py"
    click FieldDescAPI "https://github.com/erokhinvi/socrates/blob/main/app/api/field_description.py"
    click InterviewAgent "https://github.com/erokhinvi/socrates/blob/main/app/agents/interviewee_agent.py"
    click EvalAgent "https://github.com/erokhinvi/socrates/blob/main/app/agents/evaluation_agent.py"
    click FieldAgent "https://github.com/erokhinvi/socrates/blob/main/app/agents/filed_description_agent.py"
    click Prompts "https://github.com/erokhinvi/socrates/tree/main/app/agents/prompts"
    click ExtractTools "https://github.com/erokhinvi/socrates/tree/main/app/agents/tools"
    click STT "https://github.com/erokhinvi/socrates/blob/main/app/model/stt.py"
    click TTS "https://github.com/erokhinvi/socrates/blob/main/app/model/tts.py"
    click TTT "https://github.com/erokhinvi/socrates/blob/main/app/model/ttt.py"
    click Config "https://github.com/erokhinvi/socrates/blob/main/app/core/config.py"
    click OpenAI "https://github.com/erokhinvi/socrates/blob/main/app/core/openai.py"
    click Shared "https://github.com/erokhinvi/socrates/tree/main/app/utils"
    click GH "https://github.com/erokhinvi/socrates/blob/main/.github/workflows/digitalocean-deploy.yml"
    click Scripts "https://github.com/erokhinvi/socrates/blob/main/setup.sh"

    classDef frontend fill:#aedff7,stroke:#469aba,color:#000
    classDef backend fill:#d5f7c9,stroke:#6ba354,color:#000
    classDef api fill:#b2ffb2,stroke:#2e8b57,color:#000
    classDef agent fill:#fce5cd,stroke:#e69138,color:#000
    classDef storage fill:#fff2cc,stroke:#bf9000,color:#000
    classDef tools fill:#f4cccc,stroke:#cc0000,color:#000
    classDef model fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef core fill:#e1e1e1,stroke:#888888,color:#000
    classDef external fill:#ffe6cc,stroke:#ff9900,color:#000
    classDef ci fill:#cccccc,stroke:#666666,color:#000
```
