# kerevizodunu2000/rosu architecture

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

- Interactive diagram: https://gitdiagram.com/kerevizodunu2000/rosu
- Repository: https://github.com/kerevizodunu2000/rosu

## Overview

Rosu is a Windows desktop manager for osu! beatmap-pack archives and a deduplicated music library. Users unpack packs into an indexed library, search and inspect maps, then import or export sets to osu! clients or Google Drive. Separate workflows also cover installed-song capture, health checks, lost-map scans, and reports. The graph uses README-described capabilities and sampled service/UI evidence; some subsystem wiring is documented but its implementation was not sampled, so uncertain internal calls are omitted.

Main entry points: [`rosu/db.py`](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/db.py) (Library database), [`rosu/ui/main_window.py`](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/main_window.py) (Main window), [`rosu/services/extract_svc.py`](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/extract_svc.py) (Pack extraction), [`rosu/drive/client.py`](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/client.py) (Drive client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_window["Main window<br/>[main_window.py]"]
  node_settings["Settings<br/>[settings_tab.py]"]
  node_services["Services context<br/>[__init__.py]"]
end

subgraph group_ingest["Pack and library"]
  node_packs["Packs tab<br/>[packs_tab.py]"]
  node_extract["Pack extraction<br/>[extract_svc.py]"]
  node_extractor["Archive handling<br/>[extractor.py]"]
  node_library["Library operations<br/>[library_svc.py]"]
  node_db[("Library database<br/>[db.py]")]
  node_models["Map metadata<br/>[models.py]"]
end

subgraph group_discovery["Search and reporting"]
  node_searchui["Search and details<br/>[search_tab.py]"]
  node_query["Query parsing<br/>[query.py]"]
  node_search["Search engine<br/>[search.py]"]
  node_ratings["Difficulty ratings<br/>[ratings.py]"]
  node_artists["Artists view<br/>[artists_tab.py]"]
  node_report["Excel report<br/>[excel_report.py]"]
end

subgraph group_clients["Client workflows"]
  node_imports["Client import<br/>[import_svc.py]"]
  node_clienthelper["Installed-song capture<br/>[client_import.py]"]
  node_shortcuts["Shortcut jobs<br/>[export_svc.py]"]
end

subgraph group_cloud["Cloud and health"]
  node_health["Library health<br/>[health_svc.py]"]
  node_metadata["Metadata enrichment<br/>[metadata_svc.py]"]
  node_driveauth["Drive authentication<br/>[auth.py]"]
  node_driveclient["Drive client<br/>[client.py]"]
  node_bundle["Drive bundles<br/>[bundle.py]"]
end

node_user(("User"))
node_osu["osu! client"]
node_osuapi["osu! API"]
node_drive["Google Drive"]

node_user -->|"uses"| node_window
node_window -->|"uses"| node_services
node_window -->|"shows"| node_packs
node_window -->|"shows"| node_searchui
node_window -->|"shows"| node_artists
node_window -->|"shows"| node_settings
node_packs -->|"requests unpack"| node_extract
node_extract -->|"extracts archives"| node_extractor
node_extract -->|"records sets"| node_db
node_extract -.->|"uploads optionally"| node_driveclient
node_library -->|"indexes sets"| node_db
node_library -->|"reads metadata"| node_models
node_searchui -->|"parses filters"| node_query
node_searchui -->|"requests results"| node_search
node_search -->|"queries library"| node_db
node_search -->|"uses ratings"| node_ratings
node_artists -->|"reads aggregates"| node_db
node_report -->|"reads tracking data"| node_db
node_settings -->|"requests checks"| node_health
node_settings -->|"requests enrichment"| node_metadata
node_metadata -.->|"fetches metadata"| node_osuapi
node_imports -->|"dispatches sets"| node_osu
node_imports -->|"tracks client location"| node_db
node_imports -->|"captures installed maps"| node_clienthelper
node_clienthelper -->|"reads installed songs"| node_osu
node_shortcuts -->|"runs transfers"| node_imports
node_shortcuts -->|"runs unpack jobs"| node_extract
node_shortcuts -->|"uploads exports"| node_driveclient
node_driveauth -->|"authenticates"| node_drive
node_driveclient -->|"reads and writes"| node_drive
node_bundle -->|"uses uploads"| node_driveclient
node_driveclient -->|"supports location tracking"| node_db
node_health -->|"scrubs records"| node_db

click node_window "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/main_window.py"
click node_settings "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/settings_tab.py"
click node_services "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/__init__.py"
click node_packs "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/packs_tab.py"
click node_extract "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/extract_svc.py"
click node_extractor "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/extractor.py"
click node_library "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/library_svc.py"
click node_db "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/db.py"
click node_models "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/models.py"
click node_searchui "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/search_tab.py"
click node_query "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/query.py"
click node_search "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/search.py"
click node_ratings "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ratings.py"
click node_artists "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/artists_tab.py"
click node_report "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/excel_report.py"
click node_imports "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/import_svc.py"
click node_clienthelper "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/client_import.py"
click node_shortcuts "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/export_svc.py"
click node_health "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/health_svc.py"
click node_metadata "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/metadata_svc.py"
click node_driveauth "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/auth.py"
click node_driveclient "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/client.py"
click node_bundle "https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/bundle.py"

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_window,node_settings,node_services,node_user,node_osu toneBlue
class node_packs,node_extract,node_extractor,node_library,node_db,node_models toneAmber
class node_searchui,node_query,node_search,node_ratings,node_artists,node_report,node_osuapi toneMint
class node_imports,node_clienthelper,node_shortcuts toneRose
class node_health,node_metadata,node_driveauth,node_driveclient,node_bundle,node_drive toneIndigo
```

## Components

### Desktop app

- [Main window](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/main_window.py): `rosu/ui/main_window.py`
- [Settings](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/settings_tab.py): `rosu/ui/settings_tab.py`
- [Services context](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/__init__.py): `rosu/services/__init__.py`

### Pack and library

- [Packs tab](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/packs_tab.py): `rosu/ui/packs_tab.py`
- [Pack extraction](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/extract_svc.py): `rosu/services/extract_svc.py`
- [Archive handling](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/extractor.py): `rosu/extractor.py`
- [Library operations](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/library_svc.py): `rosu/services/library_svc.py`
- [Library database](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/db.py): `rosu/db.py`
- [Map metadata](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/models.py): `rosu/models.py`

### Search and reporting

- [Search and details](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/search_tab.py): `rosu/ui/search_tab.py`
- [Query parsing](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/query.py): `rosu/query.py`
- [Search engine](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/search.py): `rosu/search.py`
- [Difficulty ratings](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ratings.py): `rosu/ratings.py`
- [Artists view](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/ui/artists_tab.py): `rosu/ui/artists_tab.py`
- [Excel report](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/excel_report.py): `rosu/excel_report.py`

### Client workflows

- [Client import](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/import_svc.py): `rosu/services/import_svc.py`
- [Installed-song capture](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/client_import.py): `rosu/client_import.py`
- [Shortcut jobs](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/export_svc.py): `rosu/services/export_svc.py`

### Cloud and health

- [Library health](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/health_svc.py): `rosu/services/health_svc.py`
- [Metadata enrichment](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/services/metadata_svc.py): `rosu/services/metadata_svc.py`
- [Drive authentication](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/auth.py): `rosu/drive/auth.py`
- [Drive client](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/client.py): `rosu/drive/client.py`
- [Drive bundles](https://github.com/kerevizodunu2000/rosu/blob/main/rosu/drive/bundle.py): `rosu/drive/bundle.py`

### Other components

- **User**
- **osu! client**
- **osu! API**
- **Google Drive**

## Connections

- User → Main window: uses
- Main window → Services context: uses
- Main window → Packs tab: shows
- Main window → Search and details: shows
- Main window → Artists view: shows
- Main window → Settings: shows
- Packs tab → Pack extraction: requests unpack
- Pack extraction → Archive handling: extracts archives
- Pack extraction → Library database: records sets
- Pack extraction → Drive client: uploads optionally
- Library operations → Library database: indexes sets
- Library operations → Map metadata: reads metadata
- Search and details → Query parsing: parses filters
- Search and details → Search engine: requests results
- Search engine → Library database: queries library
- Search engine → Difficulty ratings: uses ratings
- Artists view → Library database: reads aggregates
- Excel report → Library database: reads tracking data
- Settings → Library health: requests checks
- Settings → Metadata enrichment: requests enrichment
- Metadata enrichment → osu! API: fetches metadata
- Client import → osu! client: dispatches sets
- Client import → Library database: tracks client location
- Client import → Installed-song capture: captures installed maps
- Installed-song capture → osu! client: reads installed songs
- Shortcut jobs → Client import: runs transfers
- Shortcut jobs → Pack extraction: runs unpack jobs
- Shortcut jobs → Drive client: uploads exports
- Drive authentication → Google Drive: authenticates
- Drive client → Google Drive: reads and writes
- Drive bundles → Drive client: uses uploads
- Drive client → Library database: supports location tracking
- Library health → Library database: scrubs records