# tagstudiodev/tagstudio architecture

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

- Interactive diagram: https://gitdiagram.com/tagstudiodev/tagstudio
- Repository: https://github.com/tagstudiodev/tagstudio

## Overview

##### Project type and purpose
- TagStudio is a **cross-platform desktop application** written in Python, with a **Qt-based GUI** front end and a **core library** back end responsible for file tagging, querying, and storage.
- It manages user libraries on disk, stores metadata in a `.TagStudio` folder per library (SQLite or JSON back ends), and invokes external tools (e.g., FFmpeg) for media previews.

##### File structure
- Top-level “src/tagstudio/core”: contains the **core engine**—database drivers, query language, library abstractions, utility functions.
- “src/tagstudio/qt”: contains the **GUI layer**—controllers, views, helpers, platform strings, resource loading, preview renderers.
- “pyproject.toml”, “flake.nix” / “nix/”: build, dependency, and packaging configurations.
- Tests live under “tests/”; docs under “docs/” / “mkdocs.yml”.

##### README insights
- Core features: library scanning, file tagging, custom metadata fields, search engine with AST-based parser.
- External dependencies: SQLite (via SQLAlchemy), optional JSON back end, Qt (PySide/PyQt), FFmpeg for media, ripgrep recommended for faster scans.

##### Main components & their interactions
a. Frontend (Qt GUI)
- Views: Qt widgets (main window, panels, dialogs).
- Controllers: respond to user events, call core driver.
- Preview Renderer: calls FFmpeg or bundled renderers (pydub, blender) to generate thumbnails/previews.
b. Backend/Core
- Driver/API (`core/driver.py`): single entry point for GUI & CLI to execute operations (scan, search, tag, field CRUD).
- Library Abstraction: two back ends—SQLAlchemy (SQLite) and JSON—implementing same interface.
- Query Language: tokenizer, parser, AST evaluator.
- Utilities: file‐system scanning, singleton management, subprocess wrappers, encoding helpers.
c. Storage
- `.TagStudio/ts_library.sqlite` or `ts_library.json` in user’s library folder.
- SQLAlchemy ORM models map to tables (tags, entries, fields, joins).
d. External Services
- FFmpeg CLI invoked for video/audio thumbnails.
- ripgrep (optional) for faster directory scans.
- Blender renderer (vendored) for specialized previews.
e. Build / Packaging
- pyproject.toml for dependencies.
- Nix flake + shell for reproducible dev environments.
- PyInstaller spec (tagstudio.spec) for creating executables.

##### Architectural patterns & design principles
- **Layered Architecture (GUI → Core → Storage).**
- **Strategy Pattern** for swappable back ends (SQL vs JSON).
- **MVC/MVP-style** separation: controllers mediate between Qt views and core driver.
- **Plugin‐like modules** for previews under `qt/previews/vendored`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GUI Layer
    subgraph "GUI Layer" 
        direction TB
        Views["Views (Qt Widgets)"]:::gui
        Controllers["Controllers"]:::gui
        ResourceMgr["Resource Manager"]:::gui
        PreviewRenderer["Preview Renderer"]:::gui
        VendoredPlugins["Vendored Preview Plugins"]:::gui
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        CoreEntry["Core Entry Point (ts_core.py)"]:::core
        Driver["Driver/API"]:::core
        subgraph "Library Abstraction (Strategy Pattern)"
            direction TB
            SQLLib["SQLAlchemy Backend"]:::core
            JSONLib["JSON Backend"]:::core
        end
        QueryEngine["Query Engine (tokenizer, parser, AST)"]:::core
        Utilities["Utilities"]:::core
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        SQLite["SQLite (SQLAlchemy ORM)"]:::storage
        JSONStore["JSON Storage"]:::storage
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        FFmpeg["FFmpeg CLI"]:::ext
        RipGrep["ripgrep"]:::ext
        Blender["Blender Renderer"]:::ext
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        PyProject["pyproject.toml"]:::build
        NixCfg["Nix (flake.nix + nix/)"]:::build
        PyInstallerSpec["PyInstaller Spec"]:::build
    end

    %% Relationships
    Controllers -->|"calls"| Driver
    Driver -->|"uses"| SQLLib
    Driver -->|"uses"| JSONLib
    Driver -->|"invokes"| QueryEngine
    SQLLib -->|"persists to"| SQLite
    JSONLib -->|"persists to"| JSONStore
    PreviewRenderer -->|"invokes"| FFmpeg
    PreviewRenderer -->|"invokes"| Blender
    CoreEntry --> Driver
    Utilities --> Driver
    Controllers --> ResourceMgr
    Controllers --> PreviewRenderer

    %% Build relationships
    PyProject -->|"defines deps"| NixCfg
    NixCfg -->|"creates env"| PyInstallerSpec

    %% Click Events
    click Views "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/qt/views/"
    click Controllers "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/qt/controllers/"
    click ResourceMgr "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/qt/resource_manager.py"
    click PreviewRenderer "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/qt/previews/renderer.py"
    click VendoredPlugins "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/qt/previews/vendored/"
    click Driver "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/driver.py"
    click CoreEntry "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/ts_core.py"
    click SQLLib "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/core/library/alchemy/"
    click JSONLib "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/core/library/json/"
    click QueryEngine "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/query_lang/tokenizer.py"
    click QueryEngine "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/query_lang/parser.py"
    click QueryEngine "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/query_lang/ast.py"
    click Utilities "https://github.com/tagstudiodev/tagstudio/tree/main/src/tagstudio/core/utils/"
    click SQLite "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/library/alchemy/models.py"
    click JSONStore "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/core/library/json/library.py"
    click FFmpeg "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/qt/previews/vendored/ffmpeg.py"
    click Blender "https://github.com/tagstudiodev/tagstudio/blob/main/src/tagstudio/qt/previews/vendored/blender_renderer.py"
    click PyProject "https://github.com/tagstudiodev/tagstudio/blob/main/pyproject.toml"
    click NixCfg "https://github.com/tagstudiodev/tagstudio/blob/main/flake.nix"
    click NixCfg "https://github.com/tagstudiodev/tagstudio/tree/main/nix/"
    click PyInstallerSpec "https://github.com/tagstudiodev/tagstudio/blob/main/tagstudio.spec"

    %% Styles
    classDef gui fill:#D0E8FF,stroke:#2B6CB0,color:#2B6CB0,stroke-width:1px;
    classDef core fill:#D4F1BE,stroke:#2F855A,color:#2F855A,stroke-width:1px;
    classDef storage fill:#FEEBC8,stroke:#DD6B20,color:#DD6B20,stroke-width:1px;
    classDef ext fill:#E2E8F0,stroke:#4A5568,color:#4A5568,stroke-width:1px;
    classDef build fill:#EDF2F7,stroke:#A0AEC0,color:#718096,stroke-width:1px;
```
