# tmoroney/auto-subs architecture

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

- Interactive diagram: https://gitdiagram.com/tmoroney/auto-subs
- Repository: https://github.com/tmoroney/auto-subs

## Overview

##### Main Components
- Frontend (Tauri App): Located in the AutoSubs-App directory, this component is built as a Tauri desktop application that leverages a React/TypeScript UI. It has separate modules for API calls (e.g., those in src/api/), UI components, hooks, contexts, and pages.
- Backend Transcription Server: Found in the Transcription-Server directory, this component is a Python-based server responsible for machine learning tasks including transcribing audio and speaker diarization. The provided requirements files indicate platform-specific dependencies.
- Lua Automation Server: The Lua server (located within the AutoSubs-App/src-tauri/resources folder and referenced in the README) is used to interact with DaVinci Resolve directly (adding Text+ subtitles, exporting timelines, etc.).
- API Testing & Other Scripts: The API-Testing folder (and other-scripts directory) contains files and scripts for testing API endpoints and managing legacy or additional functionality.

##### Relationships and Interactions
- The API endpoints (e.g., resolveAPI.ts, transcribeAPI.ts, transcriptionServer.ts) that facilitate communication with the transcription service.
- The Lua server which is triggered when AutoSubs is launched within DaVinci Resolve.
- The Python server and Lua server serve as backend supports:
- The Python Transcription Server handles any ML-based operations (using libraries such as MLX-Whisper and Faster-Whisper).
- The Lua server acts as a bridge between the Tauri app and DaVinci Resolve’s environment.
- External dependencies (such as the Stable-TS library) should be noted and connected to the frontend or backend components as appropriate.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly modular with distinct directories for frontend (UI), backend (transcription and automation), and API testing.
- Separation of Concerns: The UI is decoupled from the underlying processing (in Python and Lua) which facilitates maintainability and potential scalability.
- Platform-Specific Packaging: Notice the Mac-Package and Windows packaging scripts, indicating build pipelines and installers for different OS environments.

##### Relevant Technologies and Frameworks
- Tauri & React/TypeScript: Used for the modern, cross-platform desktop UI.
- Python (with virtual environments and pip): For the ML-based transcription and diarization logic.
- Lua: For integration with DaVinci Resolve.
- Build Tools & Configurations: npm (with vite.config.ts), Cargo (Rust for Tauri backend), and various configuration files (tauri.conf.json, tailwind.config.js) that manage the build and styling.
- Continuous Integration: GitHub workflows and funding files indicate community and CI/CD support.

##### Detailed Architectural Elements to Capture
- Frontend: Breakdown of directories (src, components, hooks, contexts) to show component hierarchies and API integration.
- Backend & Automation: Separate blocks for the Python server and Lua server with annotations about dependencies (requirements-* files for Python, Lua modules in the resources directory).
- Packaging/Deployment: Include nodes for build scripts (from the .github workflows, package scripts) that contribute to the one-click installer approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        A["Frontend Tauri App (React/TS)"]:::frontend
        B["UI Components (src)"]:::frontend
        C["API Service Calls (src/api)"]:::frontend
        E["Hooks (src/hooks)"]:::frontend
        F["Contexts (src/contexts)"]:::frontend
        G["Pages (src/pages)"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        H["Python Transcription Server"]:::backend
        I["Lua Automation Server"]:::backend
        M["Lua Modules"]:::backend
    end

    %% External Integration
    subgraph "External Integration"
        J["DaVinci Resolve Integration"]:::integration
    end

    %% Testing and Scripts
    subgraph "Testing & Scripts"
        K["API Testing"]:::testing
        L["Other Scripts"]:::testing
    end

    %% Data Flow Connections
    %% Frontend internal structure (grouping, not all arrows required)
    A --> B
    A --> C
    A --> E
    A --> F
    A --> G

    %% Frontend interacts with backend services
    C -->|"transcribe_audio"| H
    A -->|"launches_automation"| I

    %% Lua server interacts with its modules and external Resolve
    I -->|"loads_modules"| M
    I -->|"manages_subtitles"| J

    %% Testing connections
    K -->|"tests_API"| H
    L -->|"supports_legacy"| A

    %% Click Events for Frontend
    click A "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App"
    click B "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src"
    click C "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src/api"
    click E "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src/hooks"
    click F "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src/contexts"
    click G "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src/pages"

    %% Click Events for Backend Transcription Server
    click H "https://github.com/tmoroney/auto-subs/blob/main/Transcription-Server/server.py"

    %% Click Events for Lua Automation Server
    click I "https://github.com/tmoroney/auto-subs/blob/main/AutoSubs-App/src-tauri/resources/AutoSubs V2.lua"
    click M "https://github.com/tmoroney/auto-subs/tree/main/AutoSubs-App/src-tauri/resources/modules"

    %% Click Events for Testing & Scripts
    click K "https://github.com/tmoroney/auto-subs/tree/main/API-Testing"
    click L "https://github.com/tmoroney/auto-subs/tree/main/other-scripts"

    %% Styles
    classDef frontend fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef testing fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
```
