# zarouz/prepster architecture

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

- Interactive diagram: https://gitdiagram.com/zarouz/prepster
- Repository: https://github.com/zarouz/prepster

## Overview

##### Project Type and Purpose
- This is a full-stack (mostly backend) Flask web application providing:
– User Authentication and session management
– AI-driven interview flow (question generation, audio capture, transcription, evaluation)
– PDF report generation
– Integration with external ML and data services (LLM, Speech-to-Text, Emotional Analysis, RAG)

##### File Structure
- Top-level Flask application files:
– app.py (routes, error handlers)
– auth.py (authentication blueprint)
– config.py (env-driven settings)
– models.py + migrations/ (SQLAlchemy models + Alembic migrations)
- modules/: core “service” components:
– interview_logic (session state machine)
– llm_interface (Google Gemini calls)
– audio_utils (Google STT transcription)
– report_generator (ReportLab PDF build)
– prompt_templates, utils (text processing, RAG helpers, NLTK initialization)
- static/ + templates/: minimal frontend (Jinja2 pages, CSS/JS)
- directories for file storage: temp_uploads, reports

##### README for Additional Insights
- Confirms architecture: Flask + SQLAlchemy + PostgreSQL + Flask-Migrate
- External dependencies: Google Gemini API, Google Cloud Speech-to-Text, EmotionAPI, optional RAG DB (pgvector), NeuroSync

##### Main Components & Their Interactions
A. Web/API Layer (Flask)
– HTTP endpoints: /auth/*, /interview, /start-interview, /get-ai-message, /submit-response, /get-report
– Blueprints separate auth vs. core interview flow
B. Application/Service Layer (modules/)
– InterviewSession orchestrates the stateful flow: resume parsing, question generation, follow-ups
– LLM interface module handles Gemini queries and response cleaning
– Audio utils module sends candidate audio to Google STT, returns transcript
– Utils module supports NLTK text processing, RAG retrieval (if enabled)
– Report generator builds final PDF via ReportLab, persists to reports/
C. Data Layer
– Primary PostgreSQL DB (users, tokens, reports) via SQLAlchemy + Flask-Migrate
– Optional RAG PostgreSQL DB with pgvector extension for Retrieval-Augmented Generation
D. External Services
– Google Gemini (LLM)
– Google Cloud Speech-to-Text
– EmotionalAnalysis_API (external ML service)
– NeuroSync Player (avatar rendering)
– SMTP Mail server (Flask-Mail)
E. File Storage
– temp_uploads/ for resumes and audio files
– reports/ for generated PDF feedback
– Local .env for configuration (not committed)

##### Architectural Patterns & Principles
- Blueprint pattern in Flask for modular routing
- Layered architecture: Presentation → Service → Data
- Single responsibility in modules (LLM, audio, reporting)
- pluggable external integrations via env-driven config
- Use of migrations for DB schema versioning

– “Web/API Layer” (app.py + auth.py)
– “Application Services” (modules folder – InterviewLogic, LLM Interface, Audio, ReportGen, Utils)
– “Data Stores” (Postgres Main DB, Postgres RAG DB)
– “External Services” (Google Gemini, Google STT, EmotionAPI, NeuroSync, SMTP)
– “File Storage” (temp_uploads, reports)
– User → Browser UI (templates + static) → Flask endpoints
– Flask → Service modules → External APIs → Flask → Response to UI
– Flask → SQLAlchemy → Main DB (read/write user, session, report metadata)
– Service modules → RAG DB (optional retrieval)
– Report generator → File system → Download endpoint
c. Configuration injection from .env → config.py → all components
– Green for internal components (Flask, modules)
– Blue for data stores (Postgres)
– Orange for external services (LLM, STT, EmotionAPI, NeuroSync, SMTP)
– Gray for file storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    Browser["Browser UI"]:::internal
    Static["Static Assets"]:::internal
    Templates["Templates"]:::internal

    Browser --> Static
    Browser --> Templates
    Browser --> App_py
    Browser --> Auth_py

    %% Web/API Layer
    subgraph "Web/API Layer"
        App_py["app.py\n(Endpoints)"]:::internal
        Auth_py["auth.py\n(Authentication Blueprint)"]:::internal
        Config_py["config.py\n(Configuration)"]:::internal
    end

    %% Application Services
    subgraph "Application Services"
        InterviewLogic["Interview Logic\n(modules/interview_logic.py)"]:::internal
        LLM["LLM Interface\n(modules/llm_interface.py)"]:::internal
        AudioUtils["Audio Utils\n(modules/audio_utils.py)"]:::internal
        ReportGen["Report Generator\n(modules/report_generator.py)"]:::internal
        PromptTemplates["Prompt Templates\n(modules/prompt_templates.py)"]:::internal
        Utils["Utility Functions\n(modules/utils.py)"]:::internal
    end

    %% Data Stores
    subgraph "Data Stores"
        Models_py["models.py\n(SQLAlchemy Models)"]:::data
        Migrations["migrations/\n(Alembic)"]:::data
        MainDB["PostgreSQL Main DB\n(SQLAlchemy + Alembic)"]:::data
        RAGDB["PostgreSQL RAG DB\n(pgvector)"]:::data
    end

    %% External Services
    subgraph "External Services"
        GoogleGemini["Google Gemini API"]:::external
        GoogleSTT["Google Cloud STT"]:::external
        EmotionAPI["EmotionAPI"]:::external
        NeuroSync["NeuroSync Player"]:::external
        SMTP["SMTP Mail Server"]:::external
    end

    %% File Storage
    subgraph "File Storage"
        TempUploads["temp_uploads/"]:::storage
        ReportsFS["reports/"]:::storage
    end

    %% Flows between Web/API and Services
    App_py -->|"POST /start-interview"| InterviewLogic
    App_py -->|"GET /get-ai-message"| LLM
    App_py -->|"POST /submit-response"| AudioUtils
    App_py -->|"GET /get-report"| ReportGen
    Auth_py -->|"User CRUD"| MainDB

    %% Service interactions
    InterviewLogic -->|"generate_question()"| LLM
    InterviewLogic -->|"transcribe_audio()"| AudioUtils
    InterviewLogic -->|"evaluate_emotion()"| EmotionAPI
    InterviewLogic -->|"use_utils()"| Utils
    Utils -->|"optional RAG lookup"| RAGDB
    ReportGen -->|"save_pdf()"| ReportsFS
    ReportGen -->|"record_metadata()"| MainDB

    AudioUtils -->|"send audio"| GoogleSTT
    LLM -->|"query LLM"| GoogleGemini
    App_py -->|"render avatar"| NeuroSync
    App_py -->|"send email"| SMTP

    %% Data layer
    Models_py --> MainDB
    Migrations --> MainDB

    %% Config injection
    Config_py -.-> App_py
    Config_py -.-> Auth_py
    Config_py -.-> InterviewLogic
    Config_py -.-> LLM
    Config_py -.-> AudioUtils
    Config_py -.-> ReportGen
    Config_py -.-> Utils

    %% Click Events
    click App_py "https://github.com/zarouz/prepster/blob/main/app.py"
    click Auth_py "https://github.com/zarouz/prepster/blob/main/auth.py"
    click Config_py "https://github.com/zarouz/prepster/blob/main/config.py"
    click Models_py "https://github.com/zarouz/prepster/blob/main/models.py"
    click Migrations "https://github.com/zarouz/prepster/tree/main/migrations/"
    click LLM "https://github.com/zarouz/prepster/blob/main/modules/llm_interface.py"
    click InterviewLogic "https://github.com/zarouz/prepster/blob/main/modules/interview_logic.py"
    click AudioUtils "https://github.com/zarouz/prepster/blob/main/modules/audio_utils.py"
    click ReportGen "https://github.com/zarouz/prepster/blob/main/modules/report_generator.py"
    click PromptTemplates "https://github.com/zarouz/prepster/blob/main/modules/prompt_templates.py"
    click Utils "https://github.com/zarouz/prepster/blob/main/modules/utils.py"
    click Static "https://github.com/zarouz/prepster/tree/main/static/"
    click Templates "https://github.com/zarouz/prepster/tree/main/templates/"

    %% Styles
    classDef internal fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef data fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:1px
```
