# sang-buster/aerolex-editor architecture

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

- Interactive diagram: https://gitdiagram.com/sang-buster/aerolex-editor
- Repository: https://github.com/sang-buster/aerolex-editor

## Overview

##### Project type and purpose
- This is a full-stack, local-first transcription and subtitle editor:
- Frontend: A SvelteKit/TypeScript web UI for loading audio/video, displaying and editing transcripts in real time, and exporting subtitle formats.
- Backend: A Python CLI tool providing speech-to-text (Whisper), text analysis (Ollama, SpaCy), and format conversion utilities.

##### File structure
- Top-level:
- frontend/ – SvelteKit app, media UI, components, store, tests
- backend/ – CLI entry point (cli.py), commands (transcribe, models, shell), core libs (audio processing, Whisper engine, formatters), data folders for audio/text/proc.
- No web server: backend is a local CLI. Frontend serves a static web app that reads and writes processed files.
- Configs: package.json, tsconfig, vite.config for frontend; requirements.txt, uv/venv, pre-commit for backend.

##### README insights
- Emphasis on “local-first”: all data stays in the browser or local filesystem.
- Frontend features: media sync, waveform/spectrogram players, live transcript editing.
- Backend features: Whisper ASR, Ollama LLM summarization, multi-format export.
- Tech Stack: SvelteKit/TailwindCSS/TypeScript; Python/Whisper/Ollama/SpaCy.

##### Main components and their interactions
a. Components:
1) User’s Browser / UI
– SvelteKit app
– Media Web APIs (audio/video playback)
– UI components (Editor, Players, Panels, Tabs)
– Local store (IndexedDB or in-memory TS store)
2) Filesystem / Local Storage
– Raw audio/video files
– Transcript JSON / subtitle files
3) Backend CLI Tool
– CLI entrypoint (cli.py)
– Command modules: transcribe (calls Whisper), shell, models
– Core modules: audio.py, whisper_engine.py, formatters.py
– Data processing pipeline (data/proc: clean, llm, proc.py)
4) External Engines (all run locally)
– Whisper ASR engine
– Ollama LLM
– SpaCy NLP
b. Relationships / Data flows:
1) User uploads or selects audio/video in the browser → Frontend loads file with Media Web API.
2) Frontend can dispatch “transcribe” jobs by invoking the backend CLI (e.g., via a local shell command or file-based trigger).
3) Backend CLI reads raw audio → uses whisper_engine → produces timestamped text.
4) Optionally backend runs LLM (Ollama) / SpaCy transforms → produces summary or annotated data.
5) Backend writes output files (JSON, SRT, VTT, plaintext) to local storage.
6) Frontend watches/loads these files → displays transcripts → allows live editing → stores deltas back to local store.
7) User exports final subtitles via frontend utilities (formats generated in-browser or via calling formatters).
c. Architectural patterns / design principles:
– Separation of concerns: web UI vs. processing CLI
– Pipeline pattern in backend: raw audio → ASR → NLP → formatting
– Local-first principle: no remote servers, all processing on client/host machine
– Modular commands: each CLI command focuses on one responsibility
– Reactive UI: Svelte stores drive real-time updates on transcript edits
d. Key technologies:
– Frontend: SvelteKit, TypeScript, TailwindCSS, Vite, Media Web APIs
– Backend: Python, Whisper, Ollama, SpaCy, uv/venv, pre-commit, Ruff

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tier
    subgraph "Frontend (Local Browser)"
        direction TB
        MainEntry["main.ts"]:::frontend
        AppShell["App.svelte"]:::frontend

        subgraph "Media Layer"
            direction TB
            BottomPlayer["BottomPlayer"]:::frontend
            WaveformPlayer["WaveformPlayer"]:::frontend
            SpectrogramPlayer["SpectrogramPlayer"]:::frontend
        end

        subgraph "Transcript Layer"
            direction TB
            MainEditor["MainEditor"]:::frontend
            SubtitleNodeCard["SubtitleNodeCard"]:::frontend
            Store["store.ts"]:::frontend
        end

        subgraph "UI Panels & Tabs"
            direction TB
            RightPanel["RightPanel"]:::frontend
            ErrorList["ErrorList"]:::frontend
            Tabs["Tabs (Chat,Settings,Summary)"]:::frontend
        end

        subgraph "Export Layer"
            direction TB
            Utils["utils.ts/types.ts"]:::frontend
            Tests["tests/"]:::frontend
        end
    end

    %% Storage Tier
    subgraph "Filesystem / Local Storage"
        direction TB
        RawMedia["Raw Audio/Video Files"]:::storage
        JSONTranscripts["Transcript JSON Files"]:::storage
        SubtitleFiles["Subtitle Files (SRT/VTT)"]:::storage
    end

    %% Backend Tier
    subgraph "Backend CLI (Local Host)"
        direction TB
        CLI["cli.py"]:::backend

        subgraph "Commands"
            direction TB
            TranscribeCmd["transcribe.py"]:::backend
            ModelsCmd["models.py"]:::backend
            ShellCmd["shell.py"]:::backend
        end

        subgraph "Core Pipeline"
            direction TB
            AudioProc["audio.py"]:::backend
            WhisperEngine["whisper_engine.py"]:::backend
            Formatters["formatters.py"]:::backend
            CoreModels["models.py"]:::backend
        end

        subgraph "Data Processing Sub-Pipeline"
            direction TB
            CleanStep["clean.py"]:::backend
            LLMAugment["llm.py"]:::backend
            ProcOrch["proc.py"]:::backend
        end

        subgraph "Data Folders"
            direction TB
            DataAudio["data/audio/"]:::storage
            DataText["data/text/"]:::storage
            DataProcLogs["data/proc/"]:::storage
        end

        Requirements["requirements.txt"]:::backend
        PreCommit[".pre-commit-config.yaml"]:::backend
    end

    %% External Engines
    subgraph "External Engines"
        direction TB
        WhisperExt["Whisper ASR Engine"]:::external
        Ollama["Ollama LLM"]:::external
        SpaCy["SpaCy NLP"]:::external
    end

    %% Connections
    MainEntry -->|boots AppShell| AppShell
    AppShell -->|uses Media Layer| BottomPlayer
    AppShell --> WaveformPlayer
    AppShell --> SpectrogramPlayer

    AppShell -->|renders| MainEditor
    AppShell --> SubtitleNodeCard
    MainEditor --> Store
    SubtitleNodeCard --> Store

    AppShell --> RightPanel
    AppShell --> ErrorList
    AppShell --> Tabs

    AppShell -->|exports| Utils
    AppShell --> Tests

    AppShell -->|select/upload audio/video| RawMedia
    AppShell -->|load transcripts| JSONTranscripts
    AppShell -->|load subtitles| SubtitleFiles

    AppShell -->|invoke CLI| CLI

    CLI --> TranscribeCmd
    CLI --> ModelsCmd
    CLI --> ShellCmd

    TranscribeCmd --> AudioProc
    AudioProc --> WhisperEngine
    WhisperEngine --> WhisperExt
    WhisperEngine --> ProcOrch

    ProcOrch --> CleanStep
    CleanStep --> LLMAugment
    LLMAugment --> Ollama
    LLMAugment --> SpaCy

    ProcOrch --> Formatters
    Formatters --> JSONTranscripts
    Formatters --> SubtitleFiles

    JSONTranscripts --> AppShell
    SubtitleFiles --> AppShell

    AppShell -->|edit JSON| Store

    %% Click Events
    click MainEntry "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/main.ts"
    click AppShell "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/App.svelte"
    click BottomPlayer "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/BottomPlayer.svelte"
    click WaveformPlayer "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/WaveformPlayer.svelte"
    click SpectrogramPlayer "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/SpectrogramPlayer.svelte"
    click MainEditor "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/MainEditor.svelte"
    click SubtitleNodeCard "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/SubtitleNodeCard.svelte"
    click RightPanel "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/RightPanel.svelte"
    click ErrorList "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/components/ErrorList.svelte"
    click Tabs "https://github.com/sang-buster/aerolex-editor/tree/main/frontend/src/components/tabs/"
    click Store "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/store.ts"
    click Utils "https://github.com/sang-buster/aerolex-editor/blob/main/frontend/src/utils.ts"
    click Tests "https://github.com/sang-buster/aerolex-editor/tree/main/frontend/tests/"
    click CLI "https://github.com/sang-buster/aerolex-editor/blob/main/backend/cli.py"
    click TranscribeCmd "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/commands/transcribe.py"
    click ModelsCmd "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/commands/models.py"
    click ShellCmd "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/commands/shell.py"
    click AudioProc "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/core/audio.py"
    click WhisperEngine "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/core/whisper_engine.py"
    click Formatters "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/core/formatters.py"
    click CoreModels "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/core/models.py"
    click CleanStep "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/data/proc/clean.py"
    click LLMAugment "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/data/proc/llm.py"
    click ProcOrch "https://github.com/sang-buster/aerolex-editor/blob/main/backend/src/data/proc/proc.py"
    click DataAudio "https://github.com/sang-buster/aerolex-editor/tree/main/backend/src/data/audio/"
    click DataText "https://github.com/sang-buster/aerolex-editor/tree/main/backend/src/data/text/"
    click DataProcLogs "https://github.com/sang-buster/aerolex-editor/tree/main/backend/src/data/proc/"
    click Requirements "https://github.com/sang-buster/aerolex-editor/blob/main/backend/requirements.txt"
    click PreCommit "https://github.com/sang-buster/aerolex-editor/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef storage fill:#ECEFF1,stroke:#37474F,color:#37474F
```
