# adm-8/dsbc25 architecture

> Architecture diagram of the GitHub repository adm-8/dsbc25, 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/adm-8/dsbc25
- Repository: https://github.com/adm-8/dsbc25

## Overview

##### Project type and purpose
- This is a full‑stack, containerized web application (“Interviewee Agent”) that exposes a FastAPI backend (Uvicorn server) and serves static HTML pages as its frontend.
- Its primary function is to run conversational AI “agents” (interviewee and evaluation), leverage OpenAI’s API (and Agent SDK), perform speech‑to‑text (STT) and text‑to‑speech (TTS), and return results to the user via a browser interface.

##### File structure
- Top level:
– docker‑compose.yml, .env.example, setup.sh, dev.sh, _deploy.sh: build/deployment scripts
– config/: Nginx reverse‑proxy config + Prometheus scrape config
– certs/: TLS certificates for Nginx
– dashboards/: Grafana dashboard JSON
– .github/workflows/: CI/CD pipeline for DigitalOcean deploy
- app/ directory (core application):
– app/main.py + app/Dockerfile: application entry point & image recipe
– app/api/: FastAPI router modules (evaluation.py, interview.py)
– app/agents/: two high‑level agents and subfolders:
- prompts/: YAML system prompts + utilities
- tools/: parsers (extract_situation, action, etc.) + lie detector
- evaluation_agent.py & interviewee_agent.py orchestrate prompt/tool workflows
– app/core/: configuration & constants (OpenAI keys, environment)
– app/model/: local modules for STT, TTS, text‑to‑text (TTT) processing
– app/frontend/: static HTML for onboarding, interview, reporting, stats
– app/utils/: miscellaneous helper functions
- Monitoring & observability: Prometheus + Grafana JSON dashboards
- Deployment: orchestrated via Docker Compose behind Nginx, secrets managed via .env

##### README
- Confirms FastAPI + Uvicorn stack, external OpenAI integration, and Docker‑Compose based development & deploy steps.
- Describes agents’ directory layout and high‑level responsibilities.
- Provides CI/CD secret variables for DigitalOcean deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and entrypoint
    User["User Browser"]:::presentation
    Nginx["Nginx Reverse Proxy"]:::infra
    FastAPI["FastAPI App Server (Uvicorn)"]:::infra

    %% App Container
    subgraph "App Container (Docker)"
        API["API Layer"]:::business
        Agents["Agents Layer"]:::business
        Prompts["Prompts"]:::business
        Tools["Tools"]:::business
        Models["Model Workers"]:::business
        CoreConfig["Core Config & Constants"]:::business
        Utils["Utility Functions"]:::business
        OpenAI["External OpenAI API"]:::external
    end

    %% Orchestration and Infrastructure
    DockerCompose["Docker Compose"]:::orchestration
    Scripts["Deployment & Dev Scripts"]:::orchestration
    CICD["CI/CD Pipeline"]:::orchestration

    %% Monitoring
    subgraph "Monitoring Stack"
        Prometheus["Prometheus"]:::external
        Grafana["Grafana"]:::external
    end

    %% Connections
    User -->|"HTTP(S)"| Nginx
    Nginx -->|"Proxy pass"| FastAPI
    FastAPI -->|"routes to"| API
    API -->|"invokes"| Agents
    Agents -->|"load prompts"| Prompts
    Agents -->|"use tools"| Tools
    Agents -->|"process via"| Models
    Agents -->|"calls"| OpenAI
    OpenAI -->|"response"| Agents
    Agents -->|"return JSON/HTML"| API
    API -->|"response"| User

    FastAPI -->|"metrics endpoint"| Prometheus
    Prometheus -->|"visualize"| Grafana

    DockerCompose --> Nginx
    DockerCompose --> FastAPI
    DockerCompose --> Prometheus
    DockerCompose --> Grafana

    Scripts --> DockerCompose
    CICD --> DockerCompose

    %% Click Events
    click User "https://github.com/adm-8/dsbc25/tree/main/app/frontend/"
    click Nginx "https://github.com/adm-8/dsbc25/blob/main/config/nginx-fastapi.conf"
    click FastAPI "https://github.com/adm-8/dsbc25/blob/main/app/main.py"
    click API "https://github.com/adm-8/dsbc25/tree/main/app/api/"
    click Agents "https://github.com/adm-8/dsbc25/tree/main/app/agents/"
    click Prompts "https://github.com/adm-8/dsbc25/tree/main/app/agents/prompts/"
    click Tools "https://github.com/adm-8/dsbc25/tree/main/app/agents/tools/"
    click Models "https://github.com/adm-8/dsbc25/tree/main/app/model/"
    click OpenAI "https://github.com/adm-8/dsbc25/blob/main/app/core/openai.py"
    click CoreConfig "https://github.com/adm-8/dsbc25/blob/main/app/core/config.py"
    click Utils "https://github.com/adm-8/dsbc25/tree/main/app/utils/"
    click DockerCompose "https://github.com/adm-8/dsbc25/blob/main/docker-compose.yml"
    click Scripts "https://github.com/adm-8/dsbc25/blob/main/setup.sh"
    click CICD "https://github.com/adm-8/dsbc25/blob/main/.github/workflows/digitalocean-deploy.yml"
    click Prometheus "https://github.com/adm-8/dsbc25/blob/main/config/prometheus.yml"
    click Grafana "https://github.com/adm-8/dsbc25/blob/main/dashboards/prometheus.json"

    %% Styling Groups
    classDef presentation fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef business fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef infra fill:#d1c4e9,stroke:#8e24aa,color:#4a148c
    classDef orchestration fill:#eeeeee,stroke:#757575,color:#212121
```
