# 5rahim/seanime architecture

> Architecture diagram of the GitHub repository 5rahim/seanime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/5rahim/seanime
- Repository: https://github.com/5rahim/seanime

## Overview

#### Purpose and deployable surfaces
Seanime is a local-first media server for anime libraries, manga, downloads, streams, and playback, exposed through a browser UI, Electron desktop client, and mobile-facing server surface. The Go server starts at `main.go`; mobile embedding is `mobile/mobile.go`. The React client starts at `seanime-web/src/main.tsx`; Electron/Denshi starts at `seanime-denshi/src/main/index.ts`.

#### Application composition and API boundary
Core bootstrap owns configuration, module wiring, migrations, security, background watchers, and server lifecycle: `internal/core/app.go`, `internal/core/modules.go`, `internal/server/server.go`. HTTP handlers form the explicit UI/API boundary and route requests into domain repositories: `internal/handlers/routes.go`, `internal/handlers/request_boundary.go`, `internal/handlers/response.go`. WebSockets publish server-side changes to connected clients: `internal/events/websocket.go`, `internal/handlers/websocket.go`.

#### Persistent library and metadata pipeline
Database models and persistence cover accounts, settings, tokens, media, local files, torrent/debrid state, playlists, and scan records: `internal/database/db/db.go`, `internal/database/models/models.go`, `internal/database/db/localfiles.go`. Library scanning walks and normalizes arbitrary filesystem layouts, matches files to media, hydrates metadata, and can watch for changes: `internal/library/scanner/scan.go`, `internal/library/scanner/matcher.go`, `internal/library/scanner/watcher.go`. Anime domain collections and episode/file state are represented in `internal/library/anime/collection.go`, `internal/library/anime/entry.go`.

#### External content and tracker integrations
AniList is the principal tracker/metadata source, implemented as a generated GraphQL client plus queries and cache layer: `internal/api/anilist/client.go`, `internal/api/anilist/queries/anime.graphql`, `internal/api/anilist/localcache.go`. Metadata providers and alternative APIs sit behind provider abstractions: `internal/api/metadata_provider/provider.go`, `internal/api/mal/wrapper.go`. Offline/shared platform variants isolate availability and caching behavior: `internal/platforms/platform/platform.go`, `internal/platforms/offline_platform/offline_platform.go`.

#### Acquisition, streaming, and playback
Torrent search/selection feeds supported torrent clients or direct torrent streaming: `internal/torrents/torrent/search.go`, `internal/torrent_clients/torrent_client/repository.go`, `internal/torrentstream/stream.go`. Debrid providers abstract AllDebrid, Real-Debrid, Premiumize, and Torbox; direct-stream orchestration also supports local files and URLs: `internal/debrid/client/repository.go`, `internal/directstream/manager.go`, `internal/directstream/serve.go`. Browser playback selects direct play or transcoding/HLS-style streaming: `internal/mediastream/playback.go`, `internal/mediastream/transcode.go`, `internal/mediastream/cassette/pipeline.go`. External desktop players integrate through MPV/VLC/MPC-HC adapters: `internal/mediaplayers/mpv/mpv.go`, `internal/mediaplayers/vlc/vlc.go`.

#### Extensions and plugin runtime
Extensions provide torrent, online-stream, manga, custom-source, and plugin capabilities. The extension repository installs/configures sources and executes JavaScript through Goja: `internal/extension_repo/repository.go`, `internal/extension_repo/goja.go`, `internal/goja/goja_runtime/goja_runtime_manager.go`. Plugin-facing server APIs and UI capabilities are exposed through a separate plugin layer: `internal/plugin/plugin_app.go`, `internal/plugin/ui/ui.go`. Generated endpoint and hook contracts keep Go handlers and TypeScript API clients aligned: `codegen/main.go`, `codegen/generated/handlers.json`, `seanime-web/src/api/generated/endpoints.ts`.

#### Clients, desktop boundary, and infrastructure
The React/Rsbuild client uses generated request hooks and route modules to call the local/server API: `seanime-web/src/api/client/requests.ts`, `seanime-web/src/api/hooks/anime.hooks.ts`, `seanime-web/src/routes/__root.tsx`. Denshi is an Electron host that manages desktop runtime and embedded MPV core, while loading the web UI: `seanime-denshi/src/main/desktop-runtime.ts`, `seanime-denshi/src/main/mpv-core.ts`, `seanime-denshi/src/preload.mjs`. External services include AniList, optional Discord RPC, torrent clients (qBittorrent/Transmission), debrid services, extension-provided sources, and optional Chromecast support.

Main entry points: [`internal/handlers/routes.go`](https://github.com/5rahim/seanime/blob/main/internal/handlers/routes.go) (HTTP API boundary), [`internal/core/app.go`](https://github.com/5rahim/seanime/blob/main/internal/core/app.go) (Application bootstrap), [`internal/library/scanner/scan.go`](https://github.com/5rahim/seanime/blob/main/internal/library/scanner/scan.go) (Library scanner), [`seanime-web/src/main.tsx`](https://github.com/5rahim/seanime/blob/main/seanime-web/src/main.tsx) (React web client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server Core"]
  node_go_entry(("Go server entry<br/>Go entrypoint<br/>[main.go]"))
  node_mobile_entry(("Mobile embedding<br/>Go mobile surface<br/>[mobile.go]"))
  node_core_app["Application bootstrap<br/>core composition<br/>[app.go]"]
  node_http_api["HTTP API boundary<br/>handlers<br/>[routes.go]"]
  node_websocket["Change WebSockets<br/>event transport<br/>[websocket.go]"]
end

subgraph group_library["Library &amp; Metadata"]
  node_database[("Library database<br/>persistence<br/>[db.go]")]
  node_library_scan["Library scanner<br/>filesystem pipeline<br/>[scan.go]"]
  node_anime_library["Anime collections<br/>domain repository<br/>[collection.go]"]
  node_anilist{{"AniList integration<br/>GraphQL metadata<br/>[client.go]"}}
  node_metadata_providers["Metadata providers<br/>provider abstraction<br/>[provider.go]"]
  node_platform_variants["Platform variants<br/>availability layer<br/>[platform.go]"]
end

subgraph group_media["Acquisition &amp; Playback"]
  node_torrent_search["Torrent search<br/>acquisition service<br/>[search.go]"]
  node_torrent_clients{{"Torrent clients<br/>download adapters<br/>[repository.go]"}}
  node_direct_stream["Direct stream manager<br/>stream orchestration<br/>[manager.go]"]
  node_debrid{{"Debrid providers<br/>provider repository<br/>[repository.go]"}}
  node_playback["Browser playback<br/>media pipeline<br/>[playback.go]"]
end

subgraph group_clients["Clients &amp; Extensions"]
  node_extensions["Extension runtime<br/>Goja extension host<br/>[repository.go]"]
  node_plugin_api["Plugin API &amp; UI<br/>plugin layer<br/>[plugin_app.go]"]
  node_web_client["React web client<br/>browser client<br/>[main.tsx]"]
  node_desktop_client["Denshi desktop host<br/>Electron client<br/>[index.ts]"]
  node_codegen["API contract generation<br/>code generator<br/>[main.go]"]
end

node_go_entry -->|"starts"| node_core_app
node_mobile_entry -->|"embeds"| node_core_app
node_core_app -->|"serves"| node_http_api
node_core_app -->|"runs scans/watchers"| node_library_scan
node_core_app -->|"migrates"| node_database
node_http_api -->|"reads and writes"| node_database
node_http_api -->|"queries"| node_anime_library
node_http_api -->|"searches"| node_torrent_search
node_http_api -->|"requests streams"| node_direct_stream
node_http_api -->|"starts playback"| node_playback
node_library_scan -->|"persists files and scans"| node_database
node_library_scan -->|"matches entries"| node_anime_library
node_anime_library -->|"hydrates metadata"| node_anilist
node_metadata_providers -.->|"includes"| node_anilist
node_platform_variants -->|"controls availability"| node_metadata_providers
node_torrent_search -->|"uses source extensions"| node_extensions
node_torrent_search -->|"sends downloads"| node_torrent_clients
node_direct_stream -->|"resolves debrid streams"| node_debrid
node_direct_stream -->|"provides media"| node_playback
node_library_scan -->|"publishes changes"| node_websocket
node_websocket -->|"pushes updates"| node_web_client
node_web_client -->|"API requests"| node_http_api
node_desktop_client -->|"loads UI"| node_web_client
node_desktop_client -->|"embedded MPV playback"| node_playback
node_extensions -->|"exposes capabilities"| node_plugin_api
node_plugin_api -->|"plugin endpoints"| node_http_api
node_codegen -.->|"handler contracts"| node_http_api
node_codegen -.->|"generated endpoints"| node_web_client

click node_go_entry "https://github.com/5rahim/seanime/blob/main/main.go"
click node_mobile_entry "https://github.com/5rahim/seanime/blob/main/mobile/mobile.go"
click node_core_app "https://github.com/5rahim/seanime/blob/main/internal/core/app.go"
click node_http_api "https://github.com/5rahim/seanime/blob/main/internal/handlers/routes.go"
click node_websocket "https://github.com/5rahim/seanime/blob/main/internal/events/websocket.go"
click node_database "https://github.com/5rahim/seanime/blob/main/internal/database/db/db.go"
click node_library_scan "https://github.com/5rahim/seanime/blob/main/internal/library/scanner/scan.go"
click node_anime_library "https://github.com/5rahim/seanime/blob/main/internal/library/anime/collection.go"
click node_anilist "https://github.com/5rahim/seanime/blob/main/internal/api/anilist/client.go"
click node_metadata_providers "https://github.com/5rahim/seanime/blob/main/internal/api/metadata_provider/provider.go"
click node_platform_variants "https://github.com/5rahim/seanime/blob/main/internal/platforms/platform/platform.go"
click node_torrent_search "https://github.com/5rahim/seanime/blob/main/internal/torrents/torrent/search.go"
click node_torrent_clients "https://github.com/5rahim/seanime/blob/main/internal/torrent_clients/torrent_client/repository.go"
click node_direct_stream "https://github.com/5rahim/seanime/blob/main/internal/directstream/manager.go"
click node_debrid "https://github.com/5rahim/seanime/blob/main/internal/debrid/client/repository.go"
click node_playback "https://github.com/5rahim/seanime/blob/main/internal/mediastream/playback.go"
click node_extensions "https://github.com/5rahim/seanime/blob/main/internal/extension_repo/repository.go"
click node_plugin_api "https://github.com/5rahim/seanime/blob/main/internal/plugin/plugin_app.go"
click node_web_client "https://github.com/5rahim/seanime/blob/main/seanime-web/src/main.tsx"
click node_desktop_client "https://github.com/5rahim/seanime/blob/main/seanime-denshi/src/main/index.ts"
click node_codegen "https://github.com/5rahim/seanime/blob/main/codegen/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_go_entry,node_mobile_entry,node_core_app,node_http_api,node_websocket toneBlue
class node_database,node_library_scan,node_anime_library,node_anilist,node_metadata_providers,node_platform_variants toneAmber
class node_torrent_search,node_torrent_clients,node_direct_stream,node_debrid,node_playback toneMint
class node_extensions,node_plugin_api,node_web_client,node_desktop_client,node_codegen toneRose
```

## Components

### Server Core

- [Go server entry](https://github.com/5rahim/seanime/blob/main/main.go): Go entrypoint · `main.go`
- [Mobile embedding](https://github.com/5rahim/seanime/blob/main/mobile/mobile.go): Go mobile surface · `mobile/mobile.go`
- [Application bootstrap](https://github.com/5rahim/seanime/blob/main/internal/core/app.go): core composition · Owns modules, migrations, security, watchers, and lifecycle. · `internal/core/app.go`
- [HTTP API boundary](https://github.com/5rahim/seanime/blob/main/internal/handlers/routes.go): handlers · Routes UI requests into domain repositories. · `internal/handlers/routes.go`
- [Change WebSockets](https://github.com/5rahim/seanime/blob/main/internal/events/websocket.go): event transport · `internal/events/websocket.go`

### Library & Metadata

- [Library database](https://github.com/5rahim/seanime/blob/main/internal/database/db/db.go): persistence · Stores accounts, media, files, downloads, playlists, and scan state. · `internal/database/db/db.go`
- [Library scanner](https://github.com/5rahim/seanime/blob/main/internal/library/scanner/scan.go): filesystem pipeline · Normalizes layouts, matches files, hydrates metadata, and watches changes. · `internal/library/scanner/scan.go`
- [Anime collections](https://github.com/5rahim/seanime/blob/main/internal/library/anime/collection.go): domain repository · `internal/library/anime/collection.go`
- [AniList integration](https://github.com/5rahim/seanime/blob/main/internal/api/anilist/client.go): GraphQL metadata · Principal tracker and metadata source with local cache. · `internal/api/anilist/client.go`
- [Metadata providers](https://github.com/5rahim/seanime/blob/main/internal/api/metadata_provider/provider.go): provider abstraction · `internal/api/metadata_provider/provider.go`
- [Platform variants](https://github.com/5rahim/seanime/blob/main/internal/platforms/platform/platform.go): availability layer · Encapsulates offline and shared-platform behavior. · `internal/platforms/platform/platform.go`

### Acquisition & Playback

- [Torrent search](https://github.com/5rahim/seanime/blob/main/internal/torrents/torrent/search.go): acquisition service · `internal/torrents/torrent/search.go`
- [Torrent clients](https://github.com/5rahim/seanime/blob/main/internal/torrent_clients/torrent_client/repository.go): download adapters · Connects supported clients such as qBittorrent and Transmission. · `internal/torrent_clients/torrent_client/repository.go`
- [Direct stream manager](https://github.com/5rahim/seanime/blob/main/internal/directstream/manager.go): stream orchestration · Orchestrates local files, URLs, debrid, and torrent streams. · `internal/directstream/manager.go`
- [Debrid providers](https://github.com/5rahim/seanime/blob/main/internal/debrid/client/repository.go): provider repository · `internal/debrid/client/repository.go`
- [Browser playback](https://github.com/5rahim/seanime/blob/main/internal/mediastream/playback.go): media pipeline · Selects direct play or transcoding/HLS delivery. · `internal/mediastream/playback.go`

### Clients & Extensions

- [Extension runtime](https://github.com/5rahim/seanime/blob/main/internal/extension_repo/repository.go): Goja extension host · Installs sources and runs torrent, stream, manga, and custom extensions. · `internal/extension_repo/repository.go`
- [Plugin API & UI](https://github.com/5rahim/seanime/blob/main/internal/plugin/plugin_app.go): plugin layer · `internal/plugin/plugin_app.go`
- [React web client](https://github.com/5rahim/seanime/blob/main/seanime-web/src/main.tsx): browser client · Uses generated API hooks and route modules. · `seanime-web/src/main.tsx`
- [Denshi desktop host](https://github.com/5rahim/seanime/blob/main/seanime-denshi/src/main/index.ts): Electron client · Loads the web UI and manages embedded MPV. · `seanime-denshi/src/main/index.ts`
- [API contract generation](https://github.com/5rahim/seanime/blob/main/codegen/main.go): code generator · Keeps Go handlers and TypeScript endpoint clients aligned. · `codegen/main.go`

## Connections

- Go server entry → Application bootstrap: starts
- Mobile embedding → Application bootstrap: embeds
- Application bootstrap → HTTP API boundary: serves
- Application bootstrap → Library scanner: runs scans/watchers
- Application bootstrap → Library database: migrates
- HTTP API boundary → Library database: reads and writes
- HTTP API boundary → Anime collections: queries
- HTTP API boundary → Torrent search: searches
- HTTP API boundary → Direct stream manager: requests streams
- HTTP API boundary → Browser playback: starts playback
- Library scanner → Library database: persists files and scans
- Library scanner → Anime collections: matches entries
- Anime collections → AniList integration: hydrates metadata
- Metadata providers → AniList integration: includes
- Platform variants → Metadata providers: controls availability
- Torrent search → Extension runtime: uses source extensions
- Torrent search → Torrent clients: sends downloads
- Direct stream manager → Debrid providers: resolves debrid streams
- Direct stream manager → Browser playback: provides media
- Library scanner → Change WebSockets: publishes changes
- Change WebSockets → React web client: pushes updates
- React web client → HTTP API boundary: API requests
- Denshi desktop host → React web client: loads UI
- Denshi desktop host → Browser playback: embedded MPV playback
- Extension runtime → Plugin API & UI: exposes capabilities
- Plugin API & UI → HTTP API boundary: plugin endpoints
- API contract generation → HTTP API boundary: handler contracts
- API contract generation → React web client: generated endpoints
