# dspaul/compass architecture

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

- Interactive diagram: https://gitdiagram.com/dspaul/compass
- Repository: https://github.com/dspaul/compass

## Overview

COMPASS is a desktop organizer for tabletop-RPG resources. Its main user workflow is to gather books and other resources into collections, enrich and categorize them, then search, filter, and view them in a preferred layout. The graph includes documented capabilities whose implementation files are present in the tree, but whose source was not sampled; those feature links use README evidence. The sampled excerpts and source index provide stronger evidence for collection persistence, crash reporting, and update checks.

Main entry points: [`Source/COMPASS.Common/Domain/Codex.cs`](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Domain/Codex.cs) (Resource records), [`Source/COMPASS.Common/Features/Layouts`](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Layouts) (Library layouts), [`Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs`](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs) (Collection management), [`Source/COMPASS.Common/Shell/MainViewModel.cs`](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Shell/MainViewModel.cs) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop experience"]
  node_shell["Application shell<br/>[MainViewModel.cs]"]
  node_layouts["Library layouts<br/>[Layouts]"]
  node_crash_handler["Crash handling<br/>[CrashHandler.cs]"]
end

subgraph group_library["Library management"]
  node_codex["Resource records<br/>[Codex.cs]"]
  node_collection["Collections<br/>[CodexCollection.cs]"]
  node_collection_ops["Collection management"]
  node_import_export["Import and export<br/>[ImportExport]"]
  node_metadata["Metadata sources<br/>[Sources]"]
end

subgraph group_discovery["Organization and discovery"]
  node_tags["Tags and folders<br/>[Tags]"]
  node_filtering["Filtering and sorting<br/>[Filtering]"]
  node_layouts_config["Layout preferences<br/>[Layouts]"]
end

subgraph group_platform["Storage and services"]
  node_collection_repo[("Collection repository")]
  node_preferences["Preferences<br/>[Preferences.cs]"]
  node_covers["Cover storage"]
  node_user_files["User file storage"]
  node_compass_api["COMPASS API client"]
  node_update_manager["Update manager<br/>[UpdateManager.cs]"]
  node_github_api["GitHub API client<br/>[GitHubApiClient.cs]"]
end

node_user(("TTRPG user"))
node_user_data[("Local app data")]
node_github["GitHub releases"]

node_user -->|"uses"| node_shell
node_shell -.->|"manages"| node_collection_ops
node_user -->|"imports resources"| node_import_export
node_import_export -->|"adds resources"| node_collection
node_user -->|"enriches resources"| node_metadata
node_metadata -->|"supplies metadata"| node_codex
node_user -->|"categorizes resources"| node_tags
node_tags -->|"categorizes"| node_codex
node_user -->|"searches library"| node_filtering
node_filtering -->|"filters and sorts"| node_codex
node_user -->|"views library"| node_layouts
node_layouts -->|"displays"| node_codex
node_layouts -.->|"uses preferences"| node_layouts_config
node_collection_ops -->|"manages"| node_collection
node_collection_ops -->|"uses repository"| node_collection_repo
node_collection_repo -.->|"persists collections"| node_user_data
node_user -->|"reports crash"| node_crash_handler
node_crash_handler -->|"submits report"| node_compass_api
node_user -.->|"checks updates"| node_update_manager
node_update_manager -.->|"requests releases"| node_github_api
node_github_api -.->|"fetches releases"| node_github
node_covers -.->|"stores covers"| node_user_data
node_user_files -.->|"stores files"| node_user_data

click node_shell "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Shell/MainViewModel.cs"
click node_layouts "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Layouts"
click node_codex "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Domain/Codex.cs"
click node_collection "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Domain/CodexCollection.cs"
click node_collection_ops "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs"
click node_import_export "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/ImportExport"
click node_metadata "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Metadata/Sources"
click node_tags "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Tags"
click node_filtering "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Filtering"
click node_layouts_config "https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Layouts"
click node_collection_repo "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Persistence/Repositories/CodexCollectionXmlRepository.cs"
click node_preferences "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Settings/Preferences.cs"
click node_covers "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Covers/CoverStorageService.cs"
click node_user_files "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Persistence/Storage/UserFilesStorageService.cs"
click node_crash_handler "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Shell/CrashHandler.cs"
click node_compass_api "https://github.com/dspaul/compass/blob/master/Source/COMPASS.ApiClients/Compass/CompassApiClient.cs"
click node_update_manager "https://github.com/dspaul/compass/blob/master/Source/COMPASS.Infra/Updates/UpdateManager.cs"
click node_github_api "https://github.com/dspaul/compass/blob/master/Source/COMPASS.ApiClients/GitHub/GitHubApiClient.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_shell,node_layouts,node_crash_handler,node_user toneBlue
class node_codex,node_collection,node_collection_ops,node_import_export,node_metadata,node_user_data toneAmber
class node_tags,node_filtering,node_layouts_config toneMint
class node_collection_repo,node_preferences,node_covers,node_user_files,node_compass_api,node_update_manager,node_github_api toneRose
class node_github toneIndigo
```

## Components

### Desktop experience

- [Application shell](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Shell/MainViewModel.cs): `Source/COMPASS.Common/Shell/MainViewModel.cs`
- [Library layouts](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Layouts): `Source/COMPASS.Common/Features/Layouts`
- [Crash handling](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Shell/CrashHandler.cs): `Source/COMPASS.Common/Shell/CrashHandler.cs`

### Library management

- [Resource records](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Domain/Codex.cs): `Source/COMPASS.Common/Domain/Codex.cs`
- [Collections](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Domain/CodexCollection.cs): `Source/COMPASS.Common/Domain/CodexCollection.cs`
- [Collection management](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs): `Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs`
- [Import and export](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/ImportExport): `Source/COMPASS.Common/Features/ImportExport`
- [Metadata sources](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Metadata/Sources): `Source/COMPASS.Common/Features/Metadata/Sources`

### Organization and discovery

- [Tags and folders](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Tags): `Source/COMPASS.Common/Features/Tags`
- [Filtering and sorting](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Filtering): `Source/COMPASS.Common/Features/Filtering`
- [Layout preferences](https://github.com/dspaul/compass/tree/master/Source/COMPASS.Common/Features/Layouts): `Source/COMPASS.Common/Features/Layouts`

### Storage and services

- [Collection repository](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Persistence/Repositories/CodexCollectionXmlRepository.cs): `Source/COMPASS.Common/Features/Persistence/Repositories/CodexCollectionXmlRepository.cs`
- [Preferences](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Settings/Preferences.cs): `Source/COMPASS.Common/Features/Settings/Preferences.cs`
- [Cover storage](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Covers/CoverStorageService.cs): `Source/COMPASS.Common/Features/Covers/CoverStorageService.cs`
- [User file storage](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Common/Features/Persistence/Storage/UserFilesStorageService.cs): `Source/COMPASS.Common/Features/Persistence/Storage/UserFilesStorageService.cs`
- [COMPASS API client](https://github.com/dspaul/compass/blob/master/Source/COMPASS.ApiClients/Compass/CompassApiClient.cs): `Source/COMPASS.ApiClients/Compass/CompassApiClient.cs`
- [Update manager](https://github.com/dspaul/compass/blob/master/Source/COMPASS.Infra/Updates/UpdateManager.cs): `Source/COMPASS.Infra/Updates/UpdateManager.cs`
- [GitHub API client](https://github.com/dspaul/compass/blob/master/Source/COMPASS.ApiClients/GitHub/GitHubApiClient.cs): `Source/COMPASS.ApiClients/GitHub/GitHubApiClient.cs`

### Other components

- **TTRPG user**
- **Local app data**
- **GitHub releases**

## Connections

- TTRPG user → Application shell: uses (evidence: `README.md`)
- Application shell → Collection management: manages
- TTRPG user → Import and export: imports resources (evidence: `README.md`)
- Import and export → Collections: adds resources (evidence: `README.md`)
- TTRPG user → Metadata sources: enriches resources (evidence: `README.md`)
- Metadata sources → Resource records: supplies metadata (evidence: `README.md`)
- TTRPG user → Tags and folders: categorizes resources (evidence: `README.md`)
- Tags and folders → Resource records: categorizes (evidence: `README.md`)
- TTRPG user → Filtering and sorting: searches library (evidence: `README.md`)
- Filtering and sorting → Resource records: filters and sorts (evidence: `README.md`)
- TTRPG user → Library layouts: views library (evidence: `README.md`)
- Library layouts → Resource records: displays (evidence: `README.md`)
- Library layouts → Layout preferences: uses preferences
- Collection management → Collections: manages (evidence: `Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs`)
- Collection management → Collection repository: uses repository (evidence: `Source/COMPASS.Common/Features/CodexCollections/CollectionManager.cs`)
- Collection repository → Local app data: persists collections
- TTRPG user → Crash handling: reports crash (evidence: `Source/COMPASS.Common/Shell/CrashHandler.cs`)
- Crash handling → COMPASS API client: submits report (evidence: `Source/COMPASS.Common/Shell/CrashHandler.cs`)
- TTRPG user → Update manager: checks updates
- Update manager → GitHub API client: requests releases
- GitHub API client → GitHub releases: fetches releases
- Cover storage → Local app data: stores covers
- User file storage → Local app data: stores files