# itznan/karasu architecture

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

- Interactive diagram: https://gitdiagram.com/itznan/karasu
- Repository: https://github.com/itznan/karasu

## Overview

Karasu is a cross-platform anime and manga tracker centered on AniList. The principal workflow detects playback, identifies the title and progress, then scrobbles it to the user’s list; the app also supports local lists, discovery, social features, statistics, notifications, and integrations. The graph combines README-documented capabilities with relationships visible in sampled files and the source index; some unsampled subsystem links are therefore omitted.

Main entry points: [`src/hooks/useListMutations.ts`](https://github.com/itznan/karasu/blob/main/src/hooks/useListMutations.ts) (List mutations), [`src-tauri/src/commands/list.rs`](https://github.com/itznan/karasu/blob/main/src-tauri/src/commands/list.rs) (Native commands), [`src-tauri/src/playback/detection`](https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/detection) (Playback detection), [`src-tauri/src/playback/recognition`](https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/recognition) (Title recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_shell["App shell and routes<br/>[App.tsx]"]
end

subgraph group_tracking["Playback tracking"]
  node_detection["Playback detection"]
  node_recognition["Title recognition"]
  node_scrobbler["Progress scrobbler<br/>[scrobbler.rs]"]
end

subgraph group_lists["Lists and sync"]
  node_frontend_api["AniList API client<br/>[anilist.ts]"]
  node_bridge["Tauri API bridge<br/>[tauri.ts]"]
  node_list_ui["Anime and manga lists<br/>[MediaList.tsx]"]
  node_mutations["List mutations"]
  node_sync["Offline sync<br/>[sync.rs]"]
end

subgraph group_discovery["Discovery and community"]
  node_discovery["Search and discovery<br/>[Search.tsx]"]
  node_season_calendar["Season and calendar<br/>[Seasonal.tsx]"]
  node_franchise["Franchise graph<br/>[Franchise.tsx]"]
  node_social["Activities and forum<br/>[Social.tsx]"]
  node_statistics["Statistics and review<br/>[Statistics.tsx]"]
end

subgraph group_platform["Native services"]
  node_commands["Native commands<br/>[list.rs]"]
  node_database[("Local database<br/>[db.rs]")]
  node_library["Local library<br/>[library.rs]"]
  node_alerts["Episode alerts<br/>[mod.rs]"]
  node_discord["Discord presence<br/>[discord.rs]"]
end

node_user(("User"))
node_player["Player or browser"]
node_anilist(("AniList"))

node_user -->|"uses"| node_shell
node_player -->|"provides playback"| node_detection
node_detection -->|"identifies titles"| node_recognition
node_recognition -->|"supplies matches"| node_scrobbler
node_scrobbler -->|"updates progress"| node_anilist
node_user -->|"edits lists"| node_list_ui
node_list_ui -.->|"uses"| node_mutations
node_mutations -->|"calls"| node_frontend_api
node_frontend_api -->|"invokes commands"| node_bridge
node_bridge -->|"dispatches IPC"| node_commands
node_commands -.->|"reads and writes"| node_database
node_commands -.->|"fetches and updates"| node_anilist
node_mutations -.->|"queues offline edits"| node_sync
node_sync -.->|"persists queue"| node_database
node_user -->|"scans files"| node_library
node_user -->|"searches titles"| node_discovery
node_user -->|"browses schedules"| node_season_calendar
node_user -->|"explores relations"| node_franchise
node_user -->|"reads and writes"| node_social
node_user -->|"views insights"| node_statistics
node_alerts -->|"notifies"| node_user
node_discord -->|"shows presence"| node_user

click node_shell "https://github.com/itznan/karasu/blob/main/src/app/App.tsx"
click node_detection "https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/detection"
click node_recognition "https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/recognition"
click node_scrobbler "https://github.com/itznan/karasu/blob/main/src-tauri/src/playback/scrobbler.rs"
click node_frontend_api "https://github.com/itznan/karasu/blob/main/src/api/anilist.ts"
click node_bridge "https://github.com/itznan/karasu/blob/main/src/api/tauri.ts"
click node_commands "https://github.com/itznan/karasu/blob/main/src-tauri/src/commands/list.rs"
click node_list_ui "https://github.com/itznan/karasu/blob/main/src/pages/MediaList.tsx"
click node_mutations "https://github.com/itznan/karasu/blob/main/src/hooks/useListMutations.ts"
click node_database "https://github.com/itznan/karasu/blob/main/src-tauri/src/db.rs"
click node_sync "https://github.com/itznan/karasu/blob/main/src-tauri/src/sync.rs"
click node_library "https://github.com/itznan/karasu/blob/main/src-tauri/src/library.rs"
click node_discovery "https://github.com/itznan/karasu/blob/main/src/pages/Search.tsx"
click node_season_calendar "https://github.com/itznan/karasu/blob/main/src/pages/Seasonal.tsx"
click node_franchise "https://github.com/itznan/karasu/blob/main/src/pages/Franchise.tsx"
click node_social "https://github.com/itznan/karasu/blob/main/src/pages/Social.tsx"
click node_statistics "https://github.com/itznan/karasu/blob/main/src/pages/Statistics.tsx"
click node_alerts "https://github.com/itznan/karasu/blob/main/src-tauri/src/alerts/mod.rs"
click node_discord "https://github.com/itznan/karasu/blob/main/src-tauri/src/discord.rs"

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_shell,node_user,node_player toneBlue
class node_detection,node_recognition,node_scrobbler toneAmber
class node_frontend_api,node_bridge,node_list_ui,node_mutations,node_sync toneMint
class node_discovery,node_season_calendar,node_franchise,node_social,node_statistics toneRose
class node_commands,node_database,node_library,node_alerts,node_discord,node_anilist toneIndigo
```

## Components

### App shell

- [App shell and routes](https://github.com/itznan/karasu/blob/main/src/app/App.tsx): `src/app/App.tsx`

### Playback tracking

- [Playback detection](https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/detection): `src-tauri/src/playback/detection`
- [Title recognition](https://github.com/itznan/karasu/tree/main/src-tauri/src/playback/recognition): `src-tauri/src/playback/recognition`
- [Progress scrobbler](https://github.com/itznan/karasu/blob/main/src-tauri/src/playback/scrobbler.rs): `src-tauri/src/playback/scrobbler.rs`

### Lists and sync

- [AniList API client](https://github.com/itznan/karasu/blob/main/src/api/anilist.ts): `src/api/anilist.ts`
- [Tauri API bridge](https://github.com/itznan/karasu/blob/main/src/api/tauri.ts): `src/api/tauri.ts`
- [Anime and manga lists](https://github.com/itznan/karasu/blob/main/src/pages/MediaList.tsx): `src/pages/MediaList.tsx`
- [List mutations](https://github.com/itznan/karasu/blob/main/src/hooks/useListMutations.ts): `src/hooks/useListMutations.ts`
- [Offline sync](https://github.com/itznan/karasu/blob/main/src-tauri/src/sync.rs): `src-tauri/src/sync.rs`

### Discovery and community

- [Search and discovery](https://github.com/itznan/karasu/blob/main/src/pages/Search.tsx): `src/pages/Search.tsx`
- [Season and calendar](https://github.com/itznan/karasu/blob/main/src/pages/Seasonal.tsx): `src/pages/Seasonal.tsx`
- [Franchise graph](https://github.com/itznan/karasu/blob/main/src/pages/Franchise.tsx): `src/pages/Franchise.tsx`
- [Activities and forum](https://github.com/itznan/karasu/blob/main/src/pages/Social.tsx): `src/pages/Social.tsx`
- [Statistics and review](https://github.com/itznan/karasu/blob/main/src/pages/Statistics.tsx): `src/pages/Statistics.tsx`

### Native services

- [Native commands](https://github.com/itznan/karasu/blob/main/src-tauri/src/commands/list.rs): `src-tauri/src/commands/list.rs`
- [Local database](https://github.com/itznan/karasu/blob/main/src-tauri/src/db.rs): `src-tauri/src/db.rs`
- [Local library](https://github.com/itznan/karasu/blob/main/src-tauri/src/library.rs): `src-tauri/src/library.rs`
- [Episode alerts](https://github.com/itznan/karasu/blob/main/src-tauri/src/alerts/mod.rs): `src-tauri/src/alerts/mod.rs`
- [Discord presence](https://github.com/itznan/karasu/blob/main/src-tauri/src/discord.rs): `src-tauri/src/discord.rs`

### Other components

- **User**
- **Player or browser**
- **AniList**

## Connections

- User → App shell and routes: uses (evidence: `README.md`)
- Player or browser → Playback detection: provides playback (evidence: `README.md`)
- Playback detection → Title recognition: identifies titles (evidence: `README.md`)
- Title recognition → Progress scrobbler: supplies matches (evidence: `README.md`)
- Progress scrobbler → AniList: updates progress (evidence: `README.md`)
- User → Anime and manga lists: edits lists (evidence: `README.md`)
- Anime and manga lists → List mutations: uses
- List mutations → AniList API client: calls (evidence: `src/hooks/useListMutations.ts`)
- AniList API client → Tauri API bridge: invokes commands (evidence: `src/api/anilist.ts`)
- Tauri API bridge → Native commands: dispatches IPC (evidence: `src/api/tauri.ts`)
- Native commands → Local database: reads and writes
- Native commands → AniList: fetches and updates
- List mutations → Offline sync: queues offline edits
- Offline sync → Local database: persists queue
- User → Local library: scans files (evidence: `README.md`)
- User → Search and discovery: searches titles (evidence: `README.md`)
- User → Season and calendar: browses schedules (evidence: `README.md`)
- User → Franchise graph: explores relations (evidence: `README.md`)
- User → Activities and forum: reads and writes (evidence: `README.md`)
- User → Statistics and review: views insights (evidence: `README.md`)
- Episode alerts → User: notifies (evidence: `README.md`)
- Discord presence → User: shows presence (evidence: `README.md`)
