How stashapp/stash works
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”)