# aniraku/aniraku-backend architecture

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

- Interactive diagram: https://gitdiagram.com/aniraku/aniraku-backend
- Repository: https://github.com/aniraku/aniraku-backend

## Overview

Aniraku Backend is a Go API service for web and Android clients, centered on episode lookup and playback coordination. Requests enter through the HTTP router; playback fans out to enabled streaming providers, while episode metadata uses AniZip/TMDB resolution. The service also exposes catalog, account, import/export, and sync capabilities, with JWT authentication and guarded upstream networking. The graph follows documented routes and capabilities; some unsampled subsystem links are omitted where source excerpts do not establish the caller.

Main entry points: [`internal/api/router.go`](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/router.go) (Chi router), [`internal/api/v1/handlers.go`](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/handlers.go) (API handlers), [`internal/api/v1/proxy.go`](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/proxy.go) (Playback endpoints), [`internal/streaming/manager.go`](https://github.com/aniraku/aniraku-backend/blob/main/internal/streaming/manager.go) (Provider manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_server["HTTP service<br/>[main.go]"]
  node_router["Chi router<br/>[router.go]"]
  node_handlers["API handlers<br/>[handlers.go]"]
end

subgraph group_playback["Playback"]
  node_playback_api["Playback endpoints<br/>[proxy.go]"]
  node_manager["Provider manager<br/>[manager.go]"]
  node_providers["Streaming providers"]
  node_media_proxy["Media proxy<br/>[proxy.go]"]
end

subgraph group_metadata["Metadata"]
  node_catalog["Catalog API<br/>[catalog.go]"]
  node_anilist["AniList client<br/>[anilist_client.go]"]
  node_episodes["Episode lookup<br/>[catalog.go]"]
  node_tmdb["AniZip / TMDB resolver<br/>[resolver.go]"]
end

subgraph group_identity["Identity and accounts"]
  node_auth_mw["JWT middleware<br/>[middleware.go]"]
  node_jwks["JWKS keys<br/>[jwks.go]"]
  node_account["Account API<br/>[account.go]"]
  node_import_sync["Import and sync<br/>[importexport.go]"]
end

subgraph group_safety["Network safety"]
  node_netguard["SSRF network guard<br/>[ssrf.go]"]
end

node_clients(("Web / Android clients"))
node_upstreams{{"Provider / CDN services"}}
node_supabase[("Supabase")]

node_clients -->|"sends requests"| node_router
node_server -.->|"serves routes"| node_router
node_router -->|"routes requests"| node_handlers
node_router -->|"protects routes"| node_auth_mw
node_handlers -->|"serves catalog"| node_catalog
node_catalog -->|"queries catalog"| node_anilist
node_handlers -->|"serves episodes"| node_episodes
node_episodes -->|"resolves titles"| node_tmdb
node_handlers -->|"serves playback"| node_playback_api
node_playback_api -->|"coordinates sources"| node_manager
node_manager -->|"fans out"| node_providers
node_providers -.->|"fetches streams"| node_upstreams
node_playback_api -->|"proxies media"| node_media_proxy
node_media_proxy -->|"fetches media"| node_upstreams
node_media_proxy -->|"guards requests"| node_netguard
node_auth_mw -.->|"verifies tokens"| node_jwks
node_router -->|"routes account"| node_account
node_router -->|"routes sync"| node_import_sync
node_account -->|"reads and writes"| node_supabase
node_import_sync -.->|"syncs account data"| node_supabase

click node_server "https://github.com/aniraku/aniraku-backend/blob/main/cmd/aniraku-server/main.go"
click node_router "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/router.go"
click node_handlers "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/handlers.go"
click node_catalog "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/catalog.go"
click node_anilist "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/anilist_client.go"
click node_episodes "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/catalog.go"
click node_tmdb "https://github.com/aniraku/aniraku-backend/blob/main/internal/tmdb/resolver.go"
click node_playback_api "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/proxy.go"
click node_manager "https://github.com/aniraku/aniraku-backend/blob/main/internal/streaming/manager.go"
click node_providers "https://github.com/aniraku/aniraku-backend/tree/main/internal/streaming"
click node_media_proxy "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/proxy.go"
click node_auth_mw "https://github.com/aniraku/aniraku-backend/blob/main/internal/auth/middleware.go"
click node_jwks "https://github.com/aniraku/aniraku-backend/blob/main/internal/auth/jwks.go"
click node_account "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/account.go"
click node_import_sync "https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/importexport.go"
click node_netguard "https://github.com/aniraku/aniraku-backend/blob/main/internal/netguard/ssrf.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_server,node_router,node_handlers,node_clients toneBlue
class node_playback_api,node_manager,node_providers,node_media_proxy,node_supabase toneAmber
class node_catalog,node_anilist,node_episodes,node_tmdb toneMint
class node_auth_mw,node_jwks,node_account,node_import_sync toneRose
class node_netguard,node_upstreams toneIndigo
```

## Components

### API surface

- [HTTP service](https://github.com/aniraku/aniraku-backend/blob/main/cmd/aniraku-server/main.go): `cmd/aniraku-server/main.go`
- [Chi router](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/router.go): `internal/api/router.go`
- [API handlers](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/handlers.go): `internal/api/v1/handlers.go`

### Playback

- [Playback endpoints](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/proxy.go): `internal/api/v1/proxy.go`
- [Provider manager](https://github.com/aniraku/aniraku-backend/blob/main/internal/streaming/manager.go): `internal/streaming/manager.go`
- [Streaming providers](https://github.com/aniraku/aniraku-backend/tree/main/internal/streaming): `internal/streaming`
- [Media proxy](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/proxy.go): `internal/api/v1/proxy.go`

### Metadata

- [Catalog API](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/catalog.go): `internal/api/v1/catalog.go`
- [AniList client](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/anilist_client.go): `internal/api/v1/anilist_client.go`
- [Episode lookup](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/catalog.go): `internal/api/v1/catalog.go`
- [AniZip / TMDB resolver](https://github.com/aniraku/aniraku-backend/blob/main/internal/tmdb/resolver.go): `internal/tmdb/resolver.go`

### Identity and accounts

- [JWT middleware](https://github.com/aniraku/aniraku-backend/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`
- [JWKS keys](https://github.com/aniraku/aniraku-backend/blob/main/internal/auth/jwks.go): `internal/auth/jwks.go`
- [Account API](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/account.go): `internal/api/v1/account.go`
- [Import and sync](https://github.com/aniraku/aniraku-backend/blob/main/internal/api/v1/importexport.go): `internal/api/v1/importexport.go`

### Network safety

- [SSRF network guard](https://github.com/aniraku/aniraku-backend/blob/main/internal/netguard/ssrf.go): `internal/netguard/ssrf.go`

### Other components

- **Web / Android clients**
- **Provider / CDN services**
- **Supabase**

## Connections

- Web / Android clients → Chi router: sends requests (evidence: `README.md`)
- HTTP service → Chi router: serves routes
- Chi router → API handlers: routes requests (evidence: `internal/api/router.go`)
- Chi router → JWT middleware: protects routes (evidence: `internal/api/router.go`)
- API handlers → Catalog API: serves catalog (evidence: `README.md`)
- Catalog API → AniList client: queries catalog (evidence: `README.md`)
- API handlers → Episode lookup: serves episodes (evidence: `README.md`)
- Episode lookup → AniZip / TMDB resolver: resolves titles (evidence: `README.md`)
- API handlers → Playback endpoints: serves playback (evidence: `README.md`)
- Playback endpoints → Provider manager: coordinates sources (evidence: `README.md`)
- Provider manager → Streaming providers: fans out (evidence: `internal/streaming/manager.go`)
- Streaming providers → Provider / CDN services: fetches streams
- Playback endpoints → Media proxy: proxies media (evidence: `README.md`)
- Media proxy → Provider / CDN services: fetches media (evidence: `README.md`)
- Media proxy → SSRF network guard: guards requests (evidence: `README.md`)
- JWT middleware → JWKS keys: verifies tokens
- Chi router → Account API: routes account (evidence: `internal/api/router.go`)
- Chi router → Import and sync: routes sync (evidence: `internal/api/router.go`)
- Account API → Supabase: reads and writes (evidence: `README.md`)
- Import and sync → Supabase: syncs account data
