# jaolmos/charlamente-django architecture

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

- Interactive diagram: https://gitdiagram.com/jaolmos/charlamente-django
- Repository: https://github.com/jaolmos/charlamente-django

## Overview

Based on our review of the file tree and the README, CharlaMente is a full-stack Django web application focused on automatically transcribing and summarizing audio/video files (such as lectures, conferences, and meetings) using AI technologies (Whisper and GPT-3.5). The project encompasses a clear separation of concerns via multiple Django apps that handle core functionality, talks management (including transcription and summarization), and user authentication. Additionally, it employs background task processing (using Celery and RabbitMQ) and integrates several frontend technologies (HTML5, Bootstrap 5, HTMX) for a dynamic, responsive interface.

##### Main Components
- Client/Browser: Representing users interacting with the application through web interfaces.
- Django Web Server: The central component handling routing, HTTP requests, and serving dynamic pages.
- Apps Breakdown:
- Core App: Handles the base templates and global settings.
- Talks App: Manages the submission, processing, transcription (using Whisper), and summarization (via GPT-3.5) of talks.
- Users App: Manages user authentication, registration, and user-related views.
- Asynchronous Task Processor:
- Celery Worker: Processes background tasks, including audio transcription and summarization.
- Message Broker (RabbitMQ) connecting Django and Celery.
- Database: MySQL used for persistent storage (data related to users, talks, transcriptions, etc.).
- External AI Services:
- Whisper for audio transcription.
- GPT-3.5 for generating summaries.

##### Relationships and Data Flow
- The Django server (routes defined in the apps’ URLs) accepts the file upload.
- The processing request is queued—Celery tasks get triggered via RabbitMQ.
- Celery workers then call external AI services (Whisper for transcription and GPT-3.5 for summarization) to process the media.
- Once processed, results (both transcription and summary) are stored in the MySQL database.
- HTMX is used for updating the UI in real time, so feedback on processing states is pushed back to the client.
- Additional flows include user authentication and session management via the Users app.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear delineation between apps (core, talks, and users) supports modularity.
- Asynchronous Processing: Use of Celery and RabbitMQ decouples the processing-heavy transcription/summarization tasks from the main web request flow.
- Configurable Environments: The settings directory (with base, local, and production configurations) emphasizes a separation between different deployment environments.
- MVC (or MTV) Pattern: Django’s inherent architecture pattern effectively separates models, views, and templates.

##### Relevant Technologies and Their Roles
- Django: The core web framework managing routing, view logic, and template rendering.
- Celery & RabbitMQ: For handling asynchronous tasks.
- MySQL: The relational database used for persistent data storage.
- HTMX, Bootstrap, CSS3, and HTML5: For creating a responsive and modern frontend interface.
- Whisper and GPT-3.5: External AI services for content transcription and summarization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client/Browser"]:::frontend

    %% Django Web Server Substructure
    subgraph "Django Web Server"
        DS["Settings (base.py)"]:::backend
        DU["Routing (urls.py)"]:::backend
        DW["WSGI/ASGI (wsgi.py,asgi.py)"]:::backend
    end

    %% Django Apps
    subgraph "Django Apps"
        Core["Core App"]:::backend
        CoreTemplates["Core Templates"]:::frontend

        Talks["Talks App"]:::backend
        Transcription["Transcription Service"]:::external
        Summary["Summary Service"]:::external
        TalksTemplates["Talks Templates"]:::frontend

        Users["Users App"]:::backend
        UsersTemplates["Users Templates"]:::frontend
    end

    %% Asynchronous Task Processing
    subgraph "Asynchronous Task Processing"
        RabbitMQ["RabbitMQ"]:::task
        Celery["Celery Worker"]:::task
        CoreTasks["Core Tasks"]:::task
        TalksTasks["Talks Tasks"]:::task
    end

    %% Other Components
    DB["MySQL Database"]:::db
    SettingsConfig["Settings Config"]:::backend
    StaticAssets["Static Assets"]:::frontend

    %% External AI Services
    subgraph "External AI Services"
        Whisper["Whisper"]:::external
        GPT["GPT-3.5"]:::external
    end

    %% Data Flow Connections
    Client -->|"upload"| DU
    DU -->|"dispatch"| Core
    DU -->|"dispatch"| Talks
    DU -->|"dispatch"| Users

    %% Django Server Internal Flow
    DS --> DU
    DU --> DW
    DS -->|"config"| SettingsConfig

    %% App Internal Connections
    Core -->|"renders"| CoreTemplates
    Talks -->|"renders"| TalksTemplates
    Users -->|"renders"| UsersTemplates

    %% Talks triggering background process
    Talks -->|"queues task"| RabbitMQ

    %% Asynchronous Processing Flow
    RabbitMQ -->|"queues"| Celery
    Celery -->|"executes"| CoreTasks
    Celery -->|"executes"| TalksTasks
    Celery -->|"invokes"| Transcription
    Celery -->|"invokes"| Summary

    %% External AI Responses and DB update
    Transcription -->|"returns transcription"| DB
    Summary -->|"returns summary"| DB
    Celery -->|"updates"| DB
    DB -->|"provides data"| DU
    DU -->|"HTMX update"| Client

    %% Serving Static Assets
    Client -->|"loads"| StaticAssets

    %% Click Events
    click DS "https://github.com/jaolmos/charlamente-django/blob/main/charlamente/settings/base.py"
    click DU "https://github.com/jaolmos/charlamente-django/blob/main/charlamente/urls.py"
    click DW "https://github.com/jaolmos/charlamente-django/blob/main/charlamente/wsgi.py"
    click DW "https://github.com/jaolmos/charlamente-django/blob/main/charlamente/asgi.py"
    click Core "https://github.com/jaolmos/charlamente-django/tree/main/apps/core/"
    click CoreTemplates "https://github.com/jaolmos/charlamente-django/tree/main/apps/core/templates/core/"
    click Talks "https://github.com/jaolmos/charlamente-django/tree/main/apps/talks/"
    click Transcription "https://github.com/jaolmos/charlamente-django/blob/main/apps/talks/services/transcription.py"
    click Summary "https://github.com/jaolmos/charlamente-django/blob/main/apps/talks/services/summary.py"
    click TalksTemplates "https://github.com/jaolmos/charlamente-django/tree/main/apps/talks/templates/talks/"
    click Users "https://github.com/jaolmos/charlamente-django/tree/main/apps/users/"
    click UsersTemplates "https://github.com/jaolmos/charlamente-django/tree/main/apps/users/templates/users/"
    click Celery "https://github.com/jaolmos/charlamente-django/blob/main/charlamente/celery.py"
    click CoreTasks "https://github.com/jaolmos/charlamente-django/blob/main/apps/core/tasks.py"
    click TalksTasks "https://github.com/jaolmos/charlamente-django/blob/main/apps/talks/tasks.py"
    click SettingsConfig "https://github.com/jaolmos/charlamente-django/tree/main/charlamente/settings/"

    %% Styles
    classDef frontend fill:#ffe6a7,stroke:#333,stroke-width:2px;
    classDef backend fill:#a2d2ff,stroke:#333,stroke-width:2px;
    classDef task fill:#cdb4db,stroke:#333,stroke-width:2px;
    classDef external fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef db fill:#caffbf,stroke:#333,stroke-width:2px;
```
