# surelypal/claritydnd architecture

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

- Interactive diagram: https://gitdiagram.com/surelypal/claritydnd
- Repository: https://github.com/surelypal/claritydnd

## Overview

Clarity is a SwiftUI tabletop role-playing companion for creating and managing D&D-style characters, running campaigns, and coordinating a party locally between players and a Dungeon Master. The character workflow spans creation, a persistent character record, and the character sheet; the party workflow covers finding or hosting a lobby, connecting peers, sharing session updates, and coordinating rests. Other visible capabilities include campaign management, maps, tarot, customizable themes, and database recovery. The README is empty, and sampled source is partial, so uncertain wiring between unsampled views and services is omitted.

Main entry points: [`Core/Party/PartyManager.swift`](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager.swift) (Party coordinator), [`Core/Party/PartyManager+Messages.swift`](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager%2BMessages.swift) (Party messages), [`Core/Party/CampaignManager.swift`](https://github.com/surelypal/claritydnd/blob/main/Core/Party/CampaignManager.swift) (Campaign manager), [`Core/Models/DNDCharacter.swift`](https://github.com/surelypal/claritydnd/blob/main/Core/Models/DNDCharacter.swift) (Character model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_character["Character management"]
  node_creation["Character creation"]
  node_character_store["Character store"]
  node_character_model["Character model<br/>[DNDCharacter.swift]"]
  node_character_sheet["Character sheet"]
  node_tarot["Tarot cards<br/>[TarotTabView.swift]"]
end

subgraph group_party["Party session"]
  node_party_lobby["Party lobby"]
  node_searching["Searching view"]
  node_party_manager["Party coordinator<br/>[PartyManager.swift]"]
  node_connection["Peer connection"]
  node_messages["Party messages"]
  node_party_message["Message types<br/>[PartyMessage.swift]"]
  node_rest_voting["Rest voting"]
  node_dm_storage["DM item storage"]
  node_multipeer["Multipeer Connectivity"]
end

subgraph group_campaign["Campaign tools"]
  node_campaign_view["Campaign selection"]
  node_campaign_manager["Campaign manager"]
  node_campaign_model["Campaign model<br/>[Campaign.swift]"]
  node_game_rules["Game rules<br/>[GameRules.swift]"]
  node_map["Campaign map<br/>[MapView.swift]"]
end

subgraph group_experience["App experience"]
  node_theme_settings["Theme settings"]
  node_theme_manager["Theme manager<br/>[ThemeManager.swift]"]
  node_user_defaults[("UserDefaults")]
  node_recovery_view["Recovery screen"]
  node_recovery["Database recovery"]
  node_backup_files[("Backup files")]
end

node_user(("Player / DM"))
node_app["App entry<br/>[ClarityApp.swift]"]
node_content["App navigation<br/>[ContentView.swift]"]

node_user -->|"launches"| node_app
node_app -->|"starts"| node_content
node_user -->|"uses"| node_content
node_creation -->|"creates"| node_character_model
node_character_store -->|"manages"| node_character_model
node_character_sheet -->|"presents"| node_character_model
node_party_lobby -->|"coordinates through"| node_party_manager
node_searching -->|"cancels via"| node_party_manager
node_party_manager -->|"delegates connection"| node_connection
node_connection -->|"advertises and connects"| node_multipeer
node_party_manager -->|"dispatches messages"| node_messages
node_messages -->|"encodes and handles"| node_party_message
node_messages -->|"sends and receives"| node_multipeer
node_party_manager -->|"coordinates votes"| node_rest_voting
node_dm_storage -->|"manages storage through"| node_party_manager
node_campaign_view -->|"selects campaigns through"| node_campaign_manager
node_campaign_manager -->|"loads and saves"| node_campaign_model
node_campaign_manager -->|"reads and writes JSON"| node_backup_files
node_map -.->|"uses campaign locations"| node_campaign_model
node_theme_settings -->|"selects themes through"| node_theme_manager
node_theme_manager -->|"reads and writes selection"| node_user_defaults
node_recovery_view -->|"requests recovery actions"| node_recovery
node_recovery -->|"lists and restores"| node_backup_files

click node_app "https://github.com/surelypal/claritydnd/blob/main/ClarityApp.swift"
click node_content "https://github.com/surelypal/claritydnd/blob/main/Views/ContentView.swift"
click node_creation "https://github.com/surelypal/claritydnd/blob/main/Views/CharacterCreation/CharacterCreationView.swift"
click node_character_store "https://github.com/surelypal/claritydnd/blob/main/Core/CharacterStore.swift"
click node_character_model "https://github.com/surelypal/claritydnd/blob/main/Core/Models/DNDCharacter.swift"
click node_character_sheet "https://github.com/surelypal/claritydnd/blob/main/Views/CharacterSheet/CharacterSheetView.swift"
click node_tarot "https://github.com/surelypal/claritydnd/blob/main/Views/Tarot/TarotTabView.swift"
click node_party_lobby "https://github.com/surelypal/claritydnd/blob/main/Views/Party/PartyLobbyView.swift"
click node_searching "https://github.com/surelypal/claritydnd/blob/main/Views/Party/LobbyComponents/SearchingView.swift"
click node_party_manager "https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager.swift"
click node_connection "https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager%2BConnection.swift"
click node_messages "https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager%2BMessages.swift"
click node_party_message "https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyMessage.swift"
click node_rest_voting "https://github.com/surelypal/claritydnd/blob/main/Core/Party/RestVotingManager.swift"
click node_dm_storage "https://github.com/surelypal/claritydnd/blob/main/Views/Party/DMComponents/DMItemStorageView.swift"
click node_campaign_view "https://github.com/surelypal/claritydnd/blob/main/Views/Party/DMComponents/CampaignSelectionView.swift"
click node_campaign_manager "https://github.com/surelypal/claritydnd/blob/main/Core/Party/CampaignManager.swift"
click node_campaign_model "https://github.com/surelypal/claritydnd/blob/main/Core/Models/Campaign.swift"
click node_game_rules "https://github.com/surelypal/claritydnd/blob/main/Core/Party/GameRules.swift"
click node_map "https://github.com/surelypal/claritydnd/blob/main/Views/Map/MapView.swift"
click node_theme_settings "https://github.com/surelypal/claritydnd/blob/main/Views/Settings/ThemeSettingsView.swift"
click node_theme_manager "https://github.com/surelypal/claritydnd/blob/main/Theme/ThemeManager.swift"
click node_recovery_view "https://github.com/surelypal/claritydnd/blob/main/Views/Shared/DatabaseRecoveryView.swift"
click node_recovery "https://github.com/surelypal/claritydnd/blob/main/Core/DatabaseRecovery.swift"

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_creation,node_character_store,node_character_model,node_character_sheet,node_tarot toneBlue
class node_party_lobby,node_searching,node_party_manager,node_connection,node_messages,node_party_message,node_rest_voting,node_dm_storage,node_multipeer toneAmber
class node_campaign_view,node_campaign_manager,node_campaign_model,node_game_rules,node_map toneMint
class node_theme_settings,node_theme_manager,node_user_defaults,node_recovery_view,node_recovery,node_backup_files toneRose
class node_user toneIndigo
class node_app,node_content toneTeal
```

## Components

### Character management

- [Character creation](https://github.com/surelypal/claritydnd/blob/main/Views/CharacterCreation/CharacterCreationView.swift): `Views/CharacterCreation/CharacterCreationView.swift`
- [Character store](https://github.com/surelypal/claritydnd/blob/main/Core/CharacterStore.swift): `Core/CharacterStore.swift`
- [Character model](https://github.com/surelypal/claritydnd/blob/main/Core/Models/DNDCharacter.swift): `Core/Models/DNDCharacter.swift`
- [Character sheet](https://github.com/surelypal/claritydnd/blob/main/Views/CharacterSheet/CharacterSheetView.swift): `Views/CharacterSheet/CharacterSheetView.swift`
- [Tarot cards](https://github.com/surelypal/claritydnd/blob/main/Views/Tarot/TarotTabView.swift): `Views/Tarot/TarotTabView.swift`

### Party session

- [Party lobby](https://github.com/surelypal/claritydnd/blob/main/Views/Party/PartyLobbyView.swift): `Views/Party/PartyLobbyView.swift`
- [Searching view](https://github.com/surelypal/claritydnd/blob/main/Views/Party/LobbyComponents/SearchingView.swift): `Views/Party/LobbyComponents/SearchingView.swift`
- [Party coordinator](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager.swift): `Core/Party/PartyManager.swift`
- [Peer connection](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager%2BConnection.swift): `Core/Party/PartyManager+Connection.swift`
- [Party messages](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyManager%2BMessages.swift): `Core/Party/PartyManager+Messages.swift`
- [Message types](https://github.com/surelypal/claritydnd/blob/main/Core/Party/PartyMessage.swift): `Core/Party/PartyMessage.swift`
- [Rest voting](https://github.com/surelypal/claritydnd/blob/main/Core/Party/RestVotingManager.swift): `Core/Party/RestVotingManager.swift`
- [DM item storage](https://github.com/surelypal/claritydnd/blob/main/Views/Party/DMComponents/DMItemStorageView.swift): `Views/Party/DMComponents/DMItemStorageView.swift`
- **Multipeer Connectivity**

### Campaign tools

- [Campaign selection](https://github.com/surelypal/claritydnd/blob/main/Views/Party/DMComponents/CampaignSelectionView.swift): `Views/Party/DMComponents/CampaignSelectionView.swift`
- [Campaign manager](https://github.com/surelypal/claritydnd/blob/main/Core/Party/CampaignManager.swift): `Core/Party/CampaignManager.swift`
- [Campaign model](https://github.com/surelypal/claritydnd/blob/main/Core/Models/Campaign.swift): `Core/Models/Campaign.swift`
- [Game rules](https://github.com/surelypal/claritydnd/blob/main/Core/Party/GameRules.swift): `Core/Party/GameRules.swift`
- [Campaign map](https://github.com/surelypal/claritydnd/blob/main/Views/Map/MapView.swift): `Views/Map/MapView.swift`

### App experience

- [Theme settings](https://github.com/surelypal/claritydnd/blob/main/Views/Settings/ThemeSettingsView.swift): `Views/Settings/ThemeSettingsView.swift`
- [Theme manager](https://github.com/surelypal/claritydnd/blob/main/Theme/ThemeManager.swift): `Theme/ThemeManager.swift`
- **UserDefaults**
- [Recovery screen](https://github.com/surelypal/claritydnd/blob/main/Views/Shared/DatabaseRecoveryView.swift): `Views/Shared/DatabaseRecoveryView.swift`
- [Database recovery](https://github.com/surelypal/claritydnd/blob/main/Core/DatabaseRecovery.swift): `Core/DatabaseRecovery.swift`
- **Backup files**

### Other components

- **Player / DM**
- [App entry](https://github.com/surelypal/claritydnd/blob/main/ClarityApp.swift): `ClarityApp.swift`
- [App navigation](https://github.com/surelypal/claritydnd/blob/main/Views/ContentView.swift): `Views/ContentView.swift`

## Connections

- Player / DM → App entry: launches
- App entry → App navigation: starts
- Player / DM → App navigation: uses
- Character creation → Character model: creates
- Character store → Character model: manages
- Character sheet → Character model: presents
- Party lobby → Party coordinator: coordinates through
- Searching view → Party coordinator: cancels via
- Party coordinator → Peer connection: delegates connection
- Peer connection → Multipeer Connectivity: advertises and connects
- Party coordinator → Party messages: dispatches messages
- Party messages → Message types: encodes and handles
- Party messages → Multipeer Connectivity: sends and receives
- Party coordinator → Rest voting: coordinates votes
- DM item storage → Party coordinator: manages storage through
- Campaign selection → Campaign manager: selects campaigns through
- Campaign manager → Campaign model: loads and saves
- Campaign manager → Backup files: reads and writes JSON
- Campaign map → Campaign model: uses campaign locations
- Theme settings → Theme manager: selects themes through
- Theme manager → UserDefaults: reads and writes selection
- Recovery screen → Database recovery: requests recovery actions
- Database recovery → Backup files: lists and restores