# talktolisten/talktolisten-backend architecture

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

- Interactive diagram: https://gitdiagram.com/talktolisten/talktolisten-backend
- Repository: https://github.com/talktolisten/talktolisten-backend

## Overview

##### Project Type and Purpose
- This is a standalone back‐end microservice (FastAPI/uvicorn) for the “Talk To Listen” project.
- It exposes a RESTful API (under app/api/api_v1) for chat, voice, image, text, group‐chat, explore, and bot functionality.
- It persists data in a relational database (Alembic migration scripts) and uses Azure Storage for blobs.

##### File Structure
- Top-level: Dockerfile, server.py (entrypoint), nginx/ (reverse‐proxy), dev (local scripts), .github (CI/CD).
- app/main.py boots the FastAPI application.
- app/api/api_v1: routes (controllers), dependency modules (utils, temp_audio/image, vad), engines (image, text, voice, storage).
- app/models.py + app/schemas: ORM models & Pydantic schemas.
- app/database.py + alembic/: DB connectivity & migrations.
- CI/CD workflows in .github/workflows for build, deploy on EC2.

##### README for Additional Insights
- Uses Uvicorn for dev server.
- Instructions for Alembic migrations (DB versioning).
- Docker build & run—service containerized.
- GitHub Actions deploy to EC2.

a. Main Components
– Client(s): mobile/web front‐ends or other services calling the REST API.
– API Gateway / Nginx: optional reverse‐proxy or ingress.
– Talk To Listen Microservice (FastAPI container)
- Controllers (app/api/api_v1/routes)
- Dependency Layer (temp_audio, temp_image, vad, utils)
- Engines (image processing, text processing, voice processing, storage/azure)
- Auth & Middleware (app/auth.py, app/middleware.py)
- Database Access (app/database.py, app/models.py, alembic)
– Relational Database (e.g., PostgreSQL)
– Azure Blob Storage (external storage for images/audio)
– CI/CD Pipeline (GitHub Actions) & Docker Registry
b. Relationships & Data Flows
– Client → Nginx/API Gateway → FastAPI (HTTP JSON)
– FastAPI → Database (SQLAlchemy via app/database.py)
– FastAPI → Azure Storage (via app/api/api_v1/engines/storage/azure.py)
– Internally: Controllers call Dependency modules, which call Engines
– CI/CD: GitHub Actions builds Docker image → pushes to registry → deploys to EC2 → Nginx routes traffic into container
c. Architectural Patterns & Principles
– Layered architecture: Routes (API) → Dependency/Service layer → Engine implementations → Data layer.
– Modular “engine” abstraction for pluggable text, voice, image, storage backends.
– Database migration versioning via Alembic.
– Containerization & immutable infrastructure (Docker).
– CI/CD with GitHub Actions and infrastructure‐as‐code principles.
d. Key Technologies & Frameworks
– FastAPI, Uvicorn
– SQLAlchemy + Alembic
– Pydantic Schemas
– Azure Blob SDK
– Docker, Nginx
– GitHub Actions (YAML pipelines)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        Client("Client (Web/Mobile)"):::external
    end

    Client -->|"HTTP JSON"| Nginx("API Gateway / Reverse Proxy"):::infra
    click Nginx "https://github.com/talktolisten/talktolisten-backend/tree/main/nginx/"

    Nginx -->|"Forward HTTP"| Service("TalkToListen Service"):::internal

    subgraph "TalkToListen Service"
        subgraph "Entrypoint & Config"
            Dockerfile("Dockerfile"):::infra
            Server("server.py"):::infra
            Main("app/main.py"):::internal
            Config("app/config.py"):::internal
        end

        Dockerfile --> Server --> Main --> Config

        subgraph "Auth & Middleware"
            Auth("app/auth.py"):::internal
            Middleware("app/middleware.py"):::internal
        end
        Config --> Auth --> Middleware

        subgraph "API Layer (Routes)"
            API("app/api/api_v1/api.py"):::internal
            Chat("app/api/api_v1/routes/chat.py"):::internal
            Voice("app/api/api_v1/routes/voice.py"):::internal
            Bot("app/api/api_v1/routes/bot.py"):::internal
            Explore("app/api/api_v1/routes/explore.py"):::internal
            Group("app/api/api_v1/routes/groupchat.py"):::internal
            User("app/api/api_v1/routes/user.py"):::internal
        end
        Middleware --> API
        API --> Chat
        API --> Voice
        API --> Bot
        API --> Explore
        API --> Group
        API --> User

        subgraph "Dependency Layer"
            Utils("app/api/api_v1/dependency/utils.py"):::internal
            VAD("app/api/api_v1/dependency/vad.py"):::internal
            TempAudio("app/api/api_v1/dependency/temp_audio/concat_audios/"):::internal
            TempImage("app/api/api_v1/dependency/temp_image/"):::internal
        end
        Chat --> Utils
        Voice --> Utils
        Bot --> Utils
        Explore --> TempImage
        Voice --> VAD
        Voice --> TempAudio

        subgraph "Engine Layer"
            ImgEngine("app/api/api_v1/engines/image/base.py"):::internal
            TextEngine("app/api/api_v1/engines/text/base.py"):::internal
            TextUtil("app/api/api_v1/engines/text/utils.py"):::internal
            VoiceEngine("app/api/api_v1/engines/voice/base.py"):::internal
            StorageEngine("app/api/api_v1/engines/storage/azure.py"):::internal
        end
        TempImage --> ImgEngine
        Utils --> TextEngine
        TextEngine --> TextUtil
        Utils --> VoiceEngine
        Utils --> StorageEngine

        subgraph "Data Access Layer"
            DBConn("app/database.py"):::internal
            Models("app/models.py"):::internal
            Schemas("app/schemas/"):::internal
        end
        Main --> DBConn --> Models --> Schemas
    end

    Service -->|"SQLAlchemy"| Postgres("Relational Database (PostgreSQL)"):::external
    Service -->|"Blob Operations"| Azure("Azure Blob Storage"):::external

    subgraph "Database Migrations"
        AlembicIni("alembic.ini"):::infra
        AlembicDir("alembic/"):::infra
        Versions("alembic/versions/"):::infra
    end
    DBConn --> AlembicDir
    click AlembicIni "https://github.com/talktolisten/talktolisten-backend/blob/main/alembic.ini"
    click AlembicDir "https://github.com/talktolisten/talktolisten-backend/tree/main/alembic/"
    click Versions "https://github.com/talktolisten/talktolisten-backend/tree/main/alembic/versions/"

    subgraph "CI/CD & Deployment"
        GitHub("GitHub Actions"):::infra
        DockerReg("Docker Registry"):::infra
        EC2("EC2 Instance"):::infra
    end
    GitHub -->|"Build & Push"| DockerReg
    DockerReg -->|"Deploy"| EC2
    EC2 --> Nginx
    click GitHub "https://github.com/talktolisten/talktolisten-backend/blob/main/.github/workflows/build-deploy.yml"
    click GitHub "https://github.com/talktolisten/talktolisten-backend/blob/main/.github/workflows/cd-pipeline-1.yml"
    click GitHub "https://github.com/talktolisten/talktolisten-backend/blob/main/.github/workflows/cd-pipeline-2.yml"

    click Dockerfile "https://github.com/talktolisten/talktolisten-backend/tree/main/Dockerfile"
    click Server "https://github.com/talktolisten/talktolisten-backend/blob/main/server.py"
    click Main "https://github.com/talktolisten/talktolisten-backend/blob/main/app/main.py"
    click Config "https://github.com/talktolisten/talktolisten-backend/blob/main/app/config.py"
    click Auth "https://github.com/talktolisten/talktolisten-backend/blob/main/app/auth.py"
    click Middleware "https://github.com/talktolisten/talktolisten-backend/blob/main/app/middleware.py"
    click API "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/api.py"
    click Chat "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/chat.py"
    click Voice "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/voice.py"
    click Bot "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/bot.py"
    click Explore "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/explore.py"
    click Group "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/groupchat.py"
    click User "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/routes/user.py"
    click Utils "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/dependency/utils.py"
    click VAD "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/dependency/vad.py"
    click TempAudio "https://github.com/talktolisten/talktolisten-backend/tree/main/app/api/api_v1/dependency/temp_audio/concat_audios/"
    click TempImage "https://github.com/talktolisten/talktolisten-backend/tree/main/app/api/api_v1/dependency/temp_image/"
    click ImgEngine "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/engines/image/base.py"
    click TextEngine "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/engines/text/base.py"
    click TextUtil "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/engines/text/utils.py"
    click VoiceEngine "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/engines/voice/base.py"
    click StorageEngine "https://github.com/talktolisten/talktolisten-backend/blob/main/app/api/api_v1/engines/storage/azure.py"
    click DBConn "https://github.com/talktolisten/talktolisten-backend/blob/main/app/database.py"
    click Models "https://github.com/talktolisten/talktolisten-backend/blob/main/app/models.py"
    click Schemas "https://github.com/talktolisten/talktolisten-backend/tree/main/app/schemas/"

    classDef internal fill:#AED6F1,stroke:#1B4F72,color:#1B4F72
    classDef external fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef infra fill:#F9E79F,stroke:#B9770E,color:#B9770E
```
