# lilefab/vocal_quiz architecture

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

- Interactive diagram: https://gitdiagram.com/lilefab/vocal_quiz
- Repository: https://github.com/lilefab/vocal_quiz

## Overview

##### Main Components
- Frontend/Backend (Next.js): Emphasize that the “backend” directory contains the entire Next.js application. This includes authentication (sign-in, sign-up), various page routes (home, questions, stats), API routes (e.g., sentry, webhooks), and utility modules.
- Deep Learning Model API: The “model” directory includes the deep learning components built with PyTorch. It includes notebooks for analysis, a standalone API (server.py) that can run with Gunicorn and development scripts, and utility modules for tasks such as speech-to-text conversion.
- Database: The “database” directory contains all necessary configurations and SQL initialization scripts to deploy the PostgreSQL database.
- Other supporting components: Docker configuration files (docker-compose.yaml, Dockerfiles for each component) that indicate containerized deployment; additional configuration files for CI/CD (.gitlab-ci.yml), environment files (.env.example), and Sentry configuration for error monitoring.

##### Relationships and Interactions
- The Database (data storage, user and quiz data)
- The Model API (handling vocal input for speech-to-text conversion)
- The authentication flow, question handling, and stats pages are separate modules within the backend that interact with the database and possibly call on the deep learning logic when needed.
- You might also illustrate that the Docker Compose file ties together these containerized components, so there’s an orchestration layer that manages the integration of the backend, database, and model API.

##### Architectural Patterns and Technologies
- The backend leverages the Next.js framework, so note the usage of routing, API endpoints, middleware, and component-based UI (with React components).
- The model component is built on top of PyTorch and uses a microservice-style API that is independently deployable (e.g., via Gunicorn).
- The database component is a dockerized PostgreSQL instance configured via SQL initialization files and configuration files such as pg_hba.conf and postgresql.conf.
- Notice that the use of Docker and Docker Compose represents a containerized microservices/deployment approach.
- Modular design within the backend, such as separation of concerns for authentication, questions, and statistics—each in their own subdirectories.

- Next.js Backend (with subdivisions for authentication, API routing, questions, stats)
- Model API (highlighting deep learning, PyTorch, and supporting notebooks)
- Database (PostgreSQL container with underlying initialization/configuration)
- Docker/Deployment (the Docker Compose orchestration tying them together)
- From the Frontend/Backend to the Model API to illustrate speech-to-text processing requests.
- Optionally, from the containers to each other to show container orchestration context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Access
    U["User"]:::userStyle

    %% Frontend/Backend (Next.js)
    subgraph "Frontend/Backend (Next.js)"
        FB1["Pages, Components & Authentication\n(backend/app)"]:::backendStyle
        FB2["Database Schema\n(backend/prisma/schema.prisma)"]:::backendStyle
    end

    %% Deep Learning Model API
    subgraph "Deep Learning Model API (PyTorch)"
        M1["API Server\n(model/server.py)"]:::modelStyle
        M2["API Endpoints\n(model/api)"]:::modelStyle
        M3["Analysis Notebooks\n(model/notebooks)"]:::modelStyle
    end

    %% Database (PostgreSQL)
    subgraph "Database (PostgreSQL)"
        DB1["SQL Initialization\n(database/init.sql)"]:::dbStyle
        DB2["Config Files\n(database/pg_hba.conf & postgresql.conf)"]:::dbStyle
    end

    %% Container Orchestration
    subgraph "Container Orchestration"
        DO1["Docker Compose\n(docker-compose.yaml)"]:::dockerStyle
        DO2["Backend Dockerfile\n(backend/Dockerfile)"]:::dockerStyle
        DO3["Model Dockerfile\n(model/Dockerfile)"]:::dockerStyle
        DO4["Database Dockerfile\n(database/Dockerfile)"]:::dockerStyle
    end

    %% CI/CD and Environment Configuration
    subgraph "CI/CD & Environment"
        CI1["CI/CD Pipeline\n(.gitlab-ci.yml)"]:::ciStyle
        CI2["Environment Config\n(.env.example)"]:::ciStyle
    end

    %% Data Flow Connections
    U -->|"accesses"| FB1
    FB1 -->|"uses Prisma"| FB2
    FB1 -->|"calls for voice processing"| M1
    M1 -->|"returns processing results"| FB1
    FB1 -->|"queries/Inserts data"| DB1
    %% Indicate database config is used by DB (bidirectional storage/management within the DB component)
    DB1 ---|"configured by"| DB2

    %% Docker orchestration connections
    DO1 --> FB1
    DO1 --> M1
    DO1 --> DB1
    DO1 --> DO2
    DO1 --> DO3
    DO1 --> DO4

    %% CI/CD integration note (monitoring/deployment configuration)
    FB1 -.->|"monitored by"| CI1
    M1 -.->|"monitored by"| CI1

    %% Click Events for Frontend/Backend
    click FB1 "https://github.com/lilefab/vocal_quiz/tree/main/backend/app"
    click FB2 "https://github.com/lilefab/vocal_quiz/blob/main/backend/prisma/schema.prisma"
    click DO2 "https://github.com/lilefab/vocal_quiz/tree/main/backend/Dockerfile"

    %% Click Events for Model API
    click M1 "https://github.com/lilefab/vocal_quiz/blob/main/model/server.py"
    click M2 "https://github.com/lilefab/vocal_quiz/tree/main/model/api"
    click M3 "https://github.com/lilefab/vocal_quiz/tree/main/model/notebooks"
    click DO3 "https://github.com/lilefab/vocal_quiz/tree/main/model/Dockerfile"

    %% Click Events for Database
    click DB1 "https://github.com/lilefab/vocal_quiz/blob/main/database/init.sql"
    click DB2 "https://github.com/lilefab/vocal_quiz/blob/main/database/pg_hba.conf"
    click DO4 "https://github.com/lilefab/vocal_quiz/tree/main/database/Dockerfile"

    %% Click Events for Docker Compose and CI/CD
    click DO1 "https://github.com/lilefab/vocal_quiz/blob/main/docker-compose.yaml"
    click CI1 "https://github.com/lilefab/vocal_quiz/blob/main/.gitlab-ci.yml"
    click CI2 "https://github.com/lilefab/vocal_quiz/blob/main/.env.example"

    %% Styles
    classDef backendStyle fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef modelStyle fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef dbStyle fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef dockerStyle fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef ciStyle fill:#ececec,stroke:#95a5a6,stroke-width:2px;
    classDef userStyle fill:#ffffff,stroke:#34495e,stroke-width:2px;
    
    %% User style
    class U userStyle
```
