# mai-kun/tsundoku architecture

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

- Interactive diagram: https://gitdiagram.com/mai-kun/tsundoku
- Repository: https://github.com/mai-kun/tsundoku

## Overview

MediaTracker is a personal media-tracking application: users maintain a library of books, manga, films, shows, and games, update progress, and explore metadata, history, recommendations, and statistics. The principal flow is the UI issuing API requests to server features, which apply domain rules and persist library state; optional external providers enrich titles. The graph preserves major UI and server capabilities visible in the tree. Several UI-to-API routes and server endpoint dispatches were not shown, so those links are marked unverified rather than inferred.

Main entry points: [`MediaTracker.Server/Features/Media`](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Media) (Library and progress handlers), [`mediatracker-ui/src/app/App.svelte`](https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/app/App.svelte) (App shell and views), [`mediatracker-ui/src/shared/api/api.ts`](https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/shared/api/api.ts) (API client), [`MediaTracker.Server/Program.cs`](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Program.cs) (HTTP host and registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_ui_shell["App shell and views<br/>[App.svelte]"]
  node_ui_library["Library and media cards"]
  node_ui_detail["Media detail"]
  node_ui_features["Create, progress, settings"]
  node_ui_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and features"]
  node_api_host["HTTP host and registration<br/>[Program.cs]"]
  node_api_endpoints["HTTP endpoints<br/>[Endpoints]"]
  node_media_features["Library and progress handlers<br/>[Media]"]
  node_season_history["Seasons and history<br/>[Seasons]"]
  node_external_features["External media features<br/>[External]"]
  node_stats["Statistics and recommendations"]
  node_settings_jobs["Settings and jobs<br/>[Jobs]"]
end

subgraph group_domain["Media domain"]
  node_media_model["Media entities and rules<br/>[Entities]"]
  node_results["Result and error values<br/>[Result.cs]"]
end

subgraph group_integrations["External integrations"]
  node_metadata["Metadata aggregation"]
  node_providers["Metadata providers<br/>[ExternalApis]"]
end

subgraph group_infrastructure["Persistence and services"]
  node_database[("Application database<br/>[AppDbContext.cs]")]
  node_image_storage["Cover image storage"]
  node_job_service["Background job manager<br/>[JobManager.cs]"]
end

node_user(("Media tracker user"))

node_user -.->|"uses"| node_ui_shell
node_ui_shell -.->|"renders"| node_ui_library
node_ui_shell -.->|"opens"| node_ui_detail
node_ui_shell -.->|"hosts"| node_ui_features
node_ui_library -.->|"requests data"| node_ui_api
node_ui_detail -.->|"requests details"| node_ui_api
node_ui_features -.->|"sends updates"| node_ui_api
node_ui_api -.->|"calls"| node_api_endpoints
node_api_host -->|"imports endpoints"| node_api_endpoints
node_api_endpoints -.->|"dispatches"| node_media_features
node_media_features -.->|"queries and saves"| node_database
node_media_features -.->|"updates"| node_media_model
node_season_history -->|"updates seasons"| node_database
node_season_history -->|"uses calculator"| node_stats
node_media_features -.->|"computes statistics"| node_stats
node_external_features -->|"searches metadata"| node_metadata
node_metadata -->|"resolves providers"| node_providers
node_external_features -->|"loads relations"| node_providers
node_media_features -.->|"stores covers"| node_image_storage
node_settings_jobs -.->|"manages jobs"| node_job_service
node_api_host -->|"configures services"| node_database
node_api_host -->|"registers services"| node_job_service
node_media_features -.->|"returns outcomes"| node_results

click node_ui_shell "https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/app/App.svelte"
click node_ui_library "https://github.com/mai-kun/tsundoku/tree/main/mediatracker-ui/src/widgets/media-card"
click node_ui_detail "https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/views/MediaDetailView.svelte"
click node_ui_features "https://github.com/mai-kun/tsundoku/tree/main/mediatracker-ui/src/features"
click node_ui_api "https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/shared/api/api.ts"
click node_api_host "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Program.cs"
click node_api_endpoints "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Common/Endpoints"
click node_media_features "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Media"
click node_season_history "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Seasons"
click node_external_features "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/External"
click node_stats "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Features/Media/GetMediaStats/AdvancedStatsCalculator.cs"
click node_settings_jobs "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Jobs"
click node_media_model "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Domain/Entities"
click node_results "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Domain/Common/Result.cs"
click node_metadata "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/ExternalApis/MetadataAggregatorService.cs"
click node_providers "https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Infrastructure/ExternalApis"
click node_database "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Persistence/AppDbContext.cs"
click node_image_storage "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Storage/ImageStorageService.cs"
click node_job_service "https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Jobs/JobManager.cs"

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_ui_shell,node_ui_library,node_ui_detail,node_ui_features,node_ui_api,node_user toneBlue
class node_api_host,node_api_endpoints,node_media_features,node_season_history,node_external_features,node_stats,node_settings_jobs toneAmber
class node_media_model,node_results toneMint
class node_metadata,node_providers toneRose
class node_database,node_image_storage,node_job_service toneIndigo
```

## Components

### User interface

- [App shell and views](https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/app/App.svelte): `mediatracker-ui/src/app/App.svelte`
- [Library and media cards](https://github.com/mai-kun/tsundoku/tree/main/mediatracker-ui/src/widgets/media-card): `mediatracker-ui/src/widgets/media-card`
- [Media detail](https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/views/MediaDetailView.svelte): `mediatracker-ui/src/views/MediaDetailView.svelte`
- [Create, progress, settings](https://github.com/mai-kun/tsundoku/tree/main/mediatracker-ui/src/features): `mediatracker-ui/src/features`
- [API client](https://github.com/mai-kun/tsundoku/blob/main/mediatracker-ui/src/shared/api/api.ts): `mediatracker-ui/src/shared/api/api.ts`

### API and features

- [HTTP host and registration](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Program.cs): `MediaTracker.Server/Program.cs`
- [HTTP endpoints](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Common/Endpoints): `MediaTracker.Server/Common/Endpoints`
- [Library and progress handlers](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Media): `MediaTracker.Server/Features/Media`
- [Seasons and history](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Seasons): `MediaTracker.Server/Features/Seasons`
- [External media features](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/External): `MediaTracker.Server/Features/External`
- [Statistics and recommendations](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Features/Media/GetMediaStats/AdvancedStatsCalculator.cs): `MediaTracker.Server/Features/Media/GetMediaStats/AdvancedStatsCalculator.cs`
- [Settings and jobs](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Features/Jobs): `MediaTracker.Server/Features/Jobs`

### Media domain

- [Media entities and rules](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Domain/Entities): `MediaTracker.Server/Domain/Entities`
- [Result and error values](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Domain/Common/Result.cs): `MediaTracker.Server/Domain/Common/Result.cs`

### External integrations

- [Metadata aggregation](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/ExternalApis/MetadataAggregatorService.cs): `MediaTracker.Server/Infrastructure/ExternalApis/MetadataAggregatorService.cs`
- [Metadata providers](https://github.com/mai-kun/tsundoku/tree/main/MediaTracker.Server/Infrastructure/ExternalApis): `MediaTracker.Server/Infrastructure/ExternalApis`

### Persistence and services

- [Application database](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Persistence/AppDbContext.cs): `MediaTracker.Server/Infrastructure/Persistence/AppDbContext.cs`
- [Cover image storage](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Storage/ImageStorageService.cs): `MediaTracker.Server/Infrastructure/Storage/ImageStorageService.cs`
- [Background job manager](https://github.com/mai-kun/tsundoku/blob/main/MediaTracker.Server/Infrastructure/Jobs/JobManager.cs): `MediaTracker.Server/Infrastructure/Jobs/JobManager.cs`

### Other components

- **Media tracker user**

## Connections

- Media tracker user → App shell and views: uses
- App shell and views → Library and media cards: renders
- App shell and views → Media detail: opens
- App shell and views → Create, progress, settings: hosts
- Library and media cards → API client: requests data
- Media detail → API client: requests details
- Create, progress, settings → API client: sends updates
- API client → HTTP endpoints: calls
- HTTP host and registration → HTTP endpoints: imports endpoints (evidence: `MediaTracker.Server/Program.cs`)
- HTTP endpoints → Library and progress handlers: dispatches
- Library and progress handlers → Application database: queries and saves (evidence: `MediaTracker.Server/Features/Media/GetMediaList/MediaListQuery.cs`)
- Library and progress handlers → Media entities and rules: updates (evidence: `MediaTracker.Server/Features/Media/GetMediaList/MediaListQuery.cs`)
- Seasons and history → Application database: updates seasons (evidence: `MediaTracker.Server/Features/Seasons/UpdateSeasonProgress/UpdateSeasonProgressHandler.cs`)
- Seasons and history → Statistics and recommendations: uses calculator (evidence: `MediaTracker.Server/Features/Seasons/UpdateSeasonProgress/UpdateSeasonProgressHandler.cs`)
- Library and progress handlers → Statistics and recommendations: computes statistics (evidence: `MediaTracker.Server/Features/Media/GetMediaStats/AdvancedStatsCalculator.cs`)
- External media features → Metadata aggregation: searches metadata (evidence: `MediaTracker.Server/Features/External/SearchExternal/SearchExternalHandler.cs`)
- Metadata aggregation → Metadata providers: resolves providers (evidence: `MediaTracker.Server/Infrastructure/ExternalApis/MetadataAggregatorService.cs`)
- External media features → Metadata providers: loads relations (evidence: `MediaTracker.Server/Features/External/GetExternalRelations/GetExternalRelationsHandler.cs`)
- Library and progress handlers → Cover image storage: stores covers
- Settings and jobs → Background job manager: manages jobs (evidence: `MediaTracker.Server/Infrastructure/Jobs/JobManager.cs`)
- HTTP host and registration → Application database: configures services (evidence: `MediaTracker.Server/Program.cs`)
- HTTP host and registration → Background job manager: registers services
- Library and progress handlers → Result and error values: returns outcomes (evidence: `MediaTracker.Server/Features/Media/GetRecommendations/GetRecommendationsHandler.cs`)
