# google-marketing-solutions/ariel architecture

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

- Interactive diagram: https://gitdiagram.com/google-marketing-solutions/ariel
- Repository: https://github.com/google-marketing-solutions/ariel

## Overview

##### Project Type & Purpose
- Ariel is an open-source solution primarily built in Python, focused on processing video ads by automating dubbing into multiple languages. Its core workflow includes audio extraction, speaker diarization, speech-to-text transcription, translation, and text-to-speech conversion.
- It is structured as a multi-component system combining a Python library (in the ariel directory), a backend deployment (in the backend directory with Docker configuration), and a user interface (in the ui directory built with Angular and integrated with Google Apps Script).
- External dependencies include Google Cloud services (Cloud Run, Cloud Storage, Pub/Sub, various APIs), optional services like ElevenLabs for voice synthesis, and state-of-the-art AI models (Gemini 1.5 Flash, faster-whisper, DEMUCS, and pyannote).

##### File Structure Analysis
- The top-level "ariel" directory contains the core Python modules:
- Modules such as audio_processing.py, dubbing.py, speech_to_text.py, text_to_speech.py, translation.py, video_processing.py illustrate the component-based processing pipeline.
- A "system_settings" subdirectory with text configuration files suggests configurable workflow steps.
- The "backend" directory holds the deployment components:
- Dockerfile, app.py, and configuration examples indicate that the backend is containerized and serves as the processing server, interacting with the file storage and perhaps exposing API endpoints.
- Scripts like deploy.sh and deploy-config.sh.TEMPLATE, as well as policy JSON files, suggest integration with Google Cloud (Cloud Storage and Pub/Sub for event-driven triggers).
- The "ui" directory contains the Angular-based solution:
- An Apps Script project, Angular configuration files, and a separate package.json indicate that the UI is a web-based front-end that communicates with the backend.
- Assets (sample audio, video, voice metadata) aid in demonstrating the UI functionality.
- Other files – such as tests (for unit testing each processing component), TypeScript configuration, and additional root-level scripts – further highlight the integrated multi-language (Python and TypeScript) development environment.

##### Key Components & Their Interactions
a. Core Processing Library (Ariel Python Library):
- Main functionalities under modules like video_processing, audio_processing, dubbing, STT, translation, and TTS.
- These modules interact sequentially to extract audio, separate speakers, perform speech-to-text conversion, translate content, and finally synthesize the dubbed speech.
b. Backend Server:
- Built within the backend directory and containerized via Docker.
- Acts as the orchestrator invoking the Ariel library's functions; it also interfaces with external APIs.
- Manages storage (temporary Google Cloud Storage buckets) and handles event-driven triggers likely through Pub/Sub/EventArc.
c. User Interface (UI):
- A web-based Angular application that interacts with the backend.
- Includes deployment components via Apps Script and integrates with Google Cloud infrastructure.
- Provides a user-friendly way to configure, monitor, and trigger the dubbing workflow.
d. External Services & APIs:
- Google Cloud Platform services (Cloud Run for backend hosting, Cloud Storage for file management, Pub/Sub for notifications).
- External APIs such as:
- Gemini 1.5 Flash (used for speech-to-text and translation),
- Google Text-to-Speech and ElevenLabs (optional TTS solutions),
- Hugging Face (to access pyannote models for speaker diarization).
- These services are critical to the processing pipeline and should be represented as distinct external components interfacing with the backend and core library.

##### Architectural Patterns & Design Principles
- Separation of concerns: The clear division between the core processing library, backend orchestration, and user interface components.
- Modularity: Independent modules (each responsible for a specific processing task) allow for easier testing (as seen in the tests directory) and maintenance.
- Containerization & Cloud Integration: The backend is deployed as a Docker container, integrating seamlessly with cloud services offering scalability and event-driven processing.
- Client-Server Architecture: The web-based UI communicates with the backend server, which in turn executes the processing via the Ariel library.
- Event-driven or API-based communication is evident in how the project uses Pub/Sub and Google Cloud Storage events to trigger processing workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Angular Web App"]:::ui
    end

    %% Backend Server Layer
    subgraph "Backend Server Layer"
        BAPI["Backend API Server (Docker Container)"]:::backend
        subgraph "Deployment Components"
            BDF["Dockerfile"]:::backend
            BAPP["App Server"]:::backend
            BCFG["Config Example"]:::backend
            BDEP["Deployment Script"]:::backend
            BDEPCT["Deploy-Config TEMPLATE"]:::backend
            BRETP["Bucket Retention Policy"]:::backend
        end
        BAPI --> BDF
        BAPI --> BAPP
        BAPI --> BCFG
        BAPI --> BDEP
        BAPI --> BDEPCT
        BAPI --> BRETP
    end

    %% Processing Pipeline Layer
    subgraph "Processing Pipeline"
        VP["Video Processing Module"]:::core
        AP["Audio Processing Module"]:::core
        DB["Dubbing Module"]:::core
        STT["Speech-To-Text Module"]:::core
        TR["Translation Module"]:::core
        TTS["Text-To-Speech Module"]:::core
        subgraph "System Settings"
            Dial["Speaker Diarization Settings"]:::core
            EditTrans["Edit Translation Settings"]:::core
            Trans["Translation Settings"]:::core
        end
        VP --> AP
        AP --> DB
        DB --> STT
        STT --> TR
        TR --> TTS
        Dial -.-> AP
        EditTrans -.-> TR
        Trans -.-> TR
    end

    %% External Services & APIs Layer
    subgraph "External Services & APIs"
        GCRun["Google Cloud Run"]:::external
        GCStorage["Google Cloud Storage"]:::external
        PubSub["Google Pub/Sub"]:::external
        Gemini["Gemini 1.5 Flash API"]:::external
        GoogleTTS["Google Text-to-Speech API"]:::external
        ElevenLabs["ElevenLabs API"]:::external
        HuggingFace["Hugging Face (pyannote)"]:::external
    end

    %% Tests Layer
    subgraph "Tests"
        Tests["Unit Tests"]:::tests
    end

    %% Connections Between Layers
    UI -->|"uploads/triggers"| BAPI
    BAPI -->|"orchestrates"| VP
    BAPI -->|"stores data"| GCStorage
    BAPI -->|"handles events"| PubSub
    TTS -->|"synthesized_output"| BAPI

    %% External API Calls from Processing Modules
    STT -->|"transcription"| Gemini
    TR -->|"translation"| Gemini
    TTS -->|"synthesis1"| GoogleTTS
    TTS -->|"synthesis2"| ElevenLabs
    AP -->|"diarization"| HuggingFace

    %% Deployment Platform Connection
    BAPI -->|"hosted_on"| GCRun

    %% Testing Connections
    Tests -->|"tests_module"| VP
    Tests -->|"tests_module"| AP
    Tests -->|"tests_module"| DB
    Tests -->|"tests_module"| STT
    Tests -->|"tests_module"| TR
    Tests -->|"tests_module"| TTS

    %% Click Events - Ariel Python Library Modules
    click VP "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/video_processing.py"
    click AP "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/audio_processing.py"
    click DB "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/dubbing.py"
    click STT "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/speech_to_text.py"
    click TR "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/translation.py"
    click TTS "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/text_to_speech.py"

    %% Click Events - Ariel System Settings
    click Dial "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/system_settings/diarization.txt"
    click EditTrans "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/system_settings/edit_translation.txt"
    click Trans "https://github.com/google-marketing-solutions/ariel/blob/main/ariel/system_settings/translation.txt"

    %% Click Events - Backend Server Components
    click BDF "https://github.com/google-marketing-solutions/ariel/tree/main/backend/Dockerfile"
    click BAPP "https://github.com/google-marketing-solutions/ariel/blob/main/backend/app.py"
    click BCFG "https://github.com/google-marketing-solutions/ariel/blob/main/backend/config.json.example"
    click BDEP "https://github.com/google-marketing-solutions/ariel/blob/main/backend/deploy.sh"
    click BDEPCT "https://github.com/google-marketing-solutions/ariel/blob/main/backend/deploy-config.sh.TEMPLATE"
    click BRETP "https://github.com/google-marketing-solutions/ariel/blob/main/backend/bucket_retention_policy.json"

    %% Click Event - User Interface
    click UI "https://github.com/google-marketing-solutions/ariel/tree/main/ui/"

    %% Click Event - Tests
    click Tests "https://github.com/google-marketing-solutions/ariel/tree/main/tests/"

    %% Styles
    classDef ui fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef backend fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef core fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef external fill:#577590,stroke:#000,stroke-width:2px;
    classDef tests fill:#9b5de5,stroke:#000,stroke-width:2px;
```
