# stashapp/stash architecture

> Architecture diagram of the GitHub repository stashapp/stash, 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/stashapp/stash
- Repository: https://github.com/stashapp/stash

## Overview

##### Project Type and Purpose
- This is a full-stack, self-hosted media management web application (“Stash”)
- Backend: Go-based GraphQL/HTTP server (cmd/stash)
- Frontend: React/TypeScript application (ui/v2.5)
- CLI utility: phasher (cmd/phasher)
- Desktop wrapper: Go “desktop” package for system tray/webview clients

##### Top-Level File Structure and Architectural Layers
- cmd/…: entrypoints (stash server, phasher hash tool)
- internal/api: GraphQL schema implementation, HTTP routing, data-loader, subscriptions
- internal/…: core services (manager/task scheduler, autotag engine, DLNA, identify modules, desktop integration, plugin host)
- ui/v2.5: SPA frontend with GraphQL client, components, hooks, docs, assets
- docker/: build, CI/CD, production containers

##### Key Components to Capture
a. Clients
- Web UI: React SPA served at http://localhost:9999 (GraphQL queries, mutations, subscriptions over HTTP/WebSocket)
- CLI Tool: phasher for batch perceptual-hash generation

b. Backend Server
- API Layer: gqlgen-powered GraphQL endpoint (internal/api/server.go)
- Business Logic / Task Manager: “manager” package schedules tasks (scanning, import, generate, migrate, autotag)
- Plugin Host: RPC bridge to community or embedded Go/Python/JS plugins (internal/api/plugin_map.go, pkg/plugin)
- Scraper Engine: HTTP clients to external sites (pkg/scraper)
- DLNA Service: media-server endpoints (internal/dlna)
- Engine: metadata matching (internal/identify)
- FFmpeg Integration: video processing via local ffmpeg binary (pkg/ffmpeg)

c. Data Storage
- SQLite Database: repository layer (pkg/sqlite)
- Media Files on Disk: file scanning, thumbnail generation, phash storage

d. External Services
- Community Scrapers: third-party scraper plugins via plugin subsystem
- FFmpeg Download Service: fallback binary fetch

##### Relationships & Data Flow
1. User interacts with React UI → issues GraphQL queries/mutations/subscriptions → HTTP/WebSocket → API Layer
2. API Layer calls appropriate Resolver → delegates to Manager, Plugin host, Scraper, Identify, DLNA, or direct DB access
3. Manager schedules background tasks → interacts with file system (scan/import), calls FFmpeg wrapper for media processing, writes DB
4. Plugin host dispatches plugin calls → communicates via RPC to language-specific plugin processes → returns enriched metadata
5. Scraper engine makes outbound HTTP calls to scrape sites → returns metadata into Resolver mutations
6. Database reads/writes via SQLite driver → persists entities (scenes, performers, tags, galleries, jobs, logs)
7. GraphQL subscriptions stream job progress back to UI
8. UI renders updated data, notifications, media thumbnails

##### Architectural Patterns & Principles
- Layered modular monolith (API → service/manager → repository)
- Plugin architecture (RPC-based extensibility)
- Task-based background processing (jobs queue, GraphQL subscriptions)
- Use of DataLoader pattern in GraphQL to batch DB calls
- Separation of concerns: domain models vs. HTTP vs. persistence

##### Essential Elements
- Clear labels for each container/component (e.g., “React SPA”, “Go GraphQL Server”, “SQLite DB”, “Media FS”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        direction TB
        WebUI["React SPA"]:::client
        DesktopApp["Desktop App"]:::client
        CLITool["CLI Tool"]:::client
    end

    %% Server
    subgraph "Server"
        direction TB
        Backend["Go GraphQL Server"]:::backend
        APILayer["GraphQL API Layer"]:::backend
        Resolvers["Resolvers & Schema"]:::backend
        Manager["Task Manager"]:::backend
        PluginHost["Plugin Host"]:::backend
        Scraper["Scraper Engine"]:::backend
        Identify["Identify Engine"]:::backend
        DLNA["DLNA Service"]:::backend
        FFmpeg["FFmpeg Integration"]:::backend
    end

    %% Persistence
    subgraph "Persistence"
        direction TB
        SQLite["SQLite DB"]:::persistence
        MediaFS["Media File Store"]:::persistence
        StaticAssets["Static Assets"]:::persistence
    end

    %% External
    subgraph "External Services"
        direction TB
        StashBox["Stash-Box API"]:::external
        CommunityScrapers["Community Scrapers"]:::external
        FFmpegDownload["FFmpeg Download Service"]:::external
    end

    %% Connections: Clients to Server
    WebUI -->|"HTTP/GraphQL"| Backend
    DesktopApp -->|"HTTP/GraphQL"| Backend
    CLITool -->|"SQL"| SQLite
    CLITool -->|"File I/O"| MediaFS

    %% Server internals
    Backend -->|"route requests"| APILayer
    APILayer -->|"call resolvers"| Resolvers
    Resolvers -->|"delegate"| Manager
    Resolvers -->|"delegate"| PluginHost
    Resolvers -->|"delegate"| Scraper
    Resolvers -->|"delegate"| Identify
    Resolvers -->|"delegate"| DLNA
    Resolvers -->|"SQL"| SQLite
    Resolvers -->|"subscriptions over WS"| WebUI

    %% Manager tasks
    Manager -->|"scan/read/write"| MediaFS
    Manager -->|"exec ffmpeg"| FFmpeg
    Manager -->|"SQL"| SQLite

    %% Plugin host RPC
    PluginHost -->|"RPC"| CommunityScrapers
    PluginHost -->|"RPC"| PluginHost

    %% Scraper external
    Scraper -->|"HTTP"| StashBox
    Scraper -->|"HTTP"| CommunityScrapers

    %% Identify and DLNA
    Identify -->|"SQL"| SQLite
    DLNA -->|"serve media"| MediaFS

    %% FFmpeg download
    FFmpeg -->|"HTTP"| FFmpegDownload

    %% Click Events
    click WebUI "https://github.com/stashapp/stash/blob/develop/ui/v2.5"
    click DesktopApp "https://github.com/stashapp/stash/tree/develop/internal/desktop"
    click CLITool "https://github.com/stashapp/stash/blob/develop/cmd/phasher/main.go"
    click Backend "https://github.com/stashapp/stash/blob/develop/cmd/stash/main.go"
    click APILayer "https://github.com/stashapp/stash/blob/develop/internal/api/server.go"
    click Resolvers "https://github.com/stashapp/stash/blob/develop/internal/api/resolver.go"
    click Manager "https://github.com/stashapp/stash/tree/develop/internal/manager"
    click PluginHost "https://github.com/stashapp/stash/blob/develop/internal/api/plugin_map.go"
    click PluginHost "https://github.com/stashapp/stash/tree/develop/pkg/plugin"
    click Scraper "https://github.com/stashapp/stash/tree/develop/pkg/scraper"
    click DLNA "https://github.com/stashapp/stash/tree/develop/internal/dlna"
    click Identify "https://github.com/stashapp/stash/tree/develop/internal/identify"
    click FFmpeg "https://github.com/stashapp/stash/tree/develop/pkg/ffmpeg"
    click SQLite "https://github.com/stashapp/stash/tree/develop/pkg/sqlite"
    click StaticAssets "https://github.com/stashapp/stash/tree/develop/internal/static"
    click StaticAssets "https://github.com/stashapp/stash/tree/develop/ui/v2.5/public"
    click StashBox "https://github.com/stashapp/stash/tree/develop/pkg/stashbox"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5;
    classDef backend fill:#c8e6c9,stroke:#43a047;
    classDef persistence fill:#ffe0b2,stroke:#fb8c00;
    classDef external fill:#e0e0e0,stroke:#757575;
```
