# wackyweasel/universalcharactersheet architecture

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

- Interactive diagram: https://gitdiagram.com/wackyweasel/universalcharactersheet
- Repository: https://github.com/wackyweasel/universalcharactersheet

## Overview

Universal Character Sheet is a TTRPG character-sheet app built around managing characters and arranging configurable widgets on an infinite canvas. The main workflow starts in the app shell, selects a character or opens its sheet, and uses shared state to manage sheet data and formula-driven values. Storage workspaces can persist that data in browser storage, a local directory, or Google Drive. The graph includes documented offline installation and progress-clock capabilities; unsampled implementation links are omitted or marked unverified.

Main entry points: [`src/store/useStore.ts`](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStore.ts) (Character state), [`src/App.tsx`](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/App.tsx) (App shell), [`src/store/useStorageWorkspaceStore.ts`](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStorageWorkspaceStore.ts) (Workspace manager), [`src/components/DraggableWidget.tsx`](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/DraggableWidget.tsx) (Widget arrangement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app["App shell<br/>[App.tsx]"]
  node_character_list["Character manager<br/>[CharacterList.tsx]"]
  node_offline_install["Offline support"]
end

subgraph group_sheet["Sheets and widgets"]
  node_sheet_view["Sheet canvas<br/>[Sheet.tsx]"]
  node_draggable["Widget arrangement"]
  node_widget_set["Widget experiences"]
  node_table_widget["Table editor<br/>[TableWidget.tsx]"]
  node_dice_widgets["Dice tools"]
  node_formula_text["Formula display"]
  node_dice_overlay["Dice physics"]
end

subgraph group_state["State and logic"]
  node_global_state["Character state<br/>[useStore.ts]"]
  node_formula_engine["Formula engine<br/>[formulaEngine.ts]"]
  node_table_cells["Table cell logic<br/>[tableCells.ts]"]
  node_presets["Character presets<br/>[index.ts]"]
  node_timeline["Timeline history"]
end

subgraph group_storage["Storage and integrations"]
  node_workspace_state["Workspace manager"]
  node_workspace_registry["Workspace registry"]
  node_browser_provider[("Browser storage")]
  node_directory_provider[("Directory storage")]
  node_drive_provider[("Drive storage")]
  node_google_client["Google authorization<br/>[googleClient.ts]"]
  node_storage_warning["Storage warnings<br/>[StorageWarning.tsx]"]
  node_warning_state["Quota tracking"]
  node_storage_monitor["Storage monitor<br/>[storageMonitor.ts]"]
end

node_user(("Player"))

node_user -->|"opens"| node_app
node_app -->|"reads state"| node_global_state
node_app -->|"renders"| node_character_list
node_app -->|"renders"| node_sheet_view
node_app -->|"renders"| node_dice_overlay
node_app -->|"renders"| node_storage_warning
node_app -->|"initializes"| node_workspace_state
node_sheet_view -.->|"arranges widgets"| node_draggable
node_draggable -->|"updates sheet"| node_global_state
node_draggable -->|"renders widgets"| node_widget_set
node_widget_set -->|"updates data"| node_global_state
node_dice_widgets -->|"updates rolls"| node_global_state
node_dice_widgets -->|"uses physics"| node_dice_overlay
node_table_widget -->|"evaluates formulas"| node_formula_engine
node_table_widget -->|"uses cell logic"| node_table_cells
node_formula_text -.->|"displays formulas"| node_formula_engine
node_global_state -->|"resolves formulas"| node_formula_engine
node_global_state -->|"loads presets"| node_presets
node_timeline -->|"reads character"| node_global_state
node_workspace_state -->|"coordinates data"| node_global_state
node_workspace_state -->|"selects provider"| node_workspace_registry
node_workspace_state -->|"loads and saves"| node_browser_provider
node_workspace_state -->|"creates and loads"| node_directory_provider
node_workspace_state -->|"uses provider"| node_drive_provider
node_workspace_state -->|"authorizes access"| node_google_client
node_storage_warning -->|"shows status"| node_warning_state
node_warning_state -->|"checks quota"| node_storage_monitor
node_user -->|"installs app"| node_offline_install

click node_app "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/App.tsx"
click node_character_list "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/CharacterList.tsx"
click node_sheet_view "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/Sheet.tsx"
click node_draggable "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/DraggableWidget.tsx"
click node_widget_set "https://github.com/wackyweasel/universalcharactersheet/tree/main/src/components/widgets"
click node_table_widget "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/widgets/TableWidget.tsx"
click node_dice_widgets "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/widgets/DiceRollerWidget.tsx"
click node_formula_text "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/InlineFormulaText.tsx"
click node_dice_overlay "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/DicePhysicsOverlay.tsx"
click node_global_state "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStore.ts"
click node_formula_engine "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/formulaEngine.ts"
click node_table_cells "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/tableCells.ts"
click node_presets "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/presets/index.ts"
click node_timeline "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useTimelineStore.ts"
click node_workspace_state "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStorageWorkspaceStore.ts"
click node_workspace_registry "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/workspaceRegistry.ts"
click node_browser_provider "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/browserWorkspaceProvider.ts"
click node_directory_provider "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/directoryWorkspaceProvider.ts"
click node_drive_provider "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/googleDriveWorkspaceProvider.ts"
click node_google_client "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/google/googleClient.ts"
click node_storage_warning "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/StorageWarning.tsx"
click node_warning_state "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStorageWarningStore.ts"
click node_storage_monitor "https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/storageMonitor.ts"
click node_offline_install "https://github.com/wackyweasel/universalcharactersheet/tree/main/src/pwa"

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_app,node_character_list,node_offline_install toneBlue
class node_sheet_view,node_draggable,node_widget_set,node_table_widget,node_dice_widgets,node_formula_text,node_dice_overlay toneAmber
class node_global_state,node_formula_engine,node_table_cells,node_presets,node_timeline toneMint
class node_workspace_state,node_workspace_registry,node_browser_provider,node_directory_provider,node_drive_provider,node_google_client,node_storage_warning,node_warning_state,node_storage_monitor toneRose
class node_user toneIndigo
```

## Components

### Application

- [App shell](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/App.tsx): `src/App.tsx`
- [Character manager](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/CharacterList.tsx): `src/components/CharacterList.tsx`
- [Offline support](https://github.com/wackyweasel/universalcharactersheet/tree/main/src/pwa): `src/pwa`

### Sheets and widgets

- [Sheet canvas](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/Sheet.tsx): `src/components/Sheet.tsx`
- [Widget arrangement](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/DraggableWidget.tsx): `src/components/DraggableWidget.tsx`
- [Widget experiences](https://github.com/wackyweasel/universalcharactersheet/tree/main/src/components/widgets): `src/components/widgets`
- [Table editor](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/widgets/TableWidget.tsx): `src/components/widgets/TableWidget.tsx`
- [Dice tools](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/widgets/DiceRollerWidget.tsx): `src/components/widgets/DiceRollerWidget.tsx`
- [Formula display](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/InlineFormulaText.tsx): `src/components/InlineFormulaText.tsx`
- [Dice physics](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/DicePhysicsOverlay.tsx): `src/components/DicePhysicsOverlay.tsx`

### State and logic

- [Character state](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStore.ts): `src/store/useStore.ts`
- [Formula engine](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/formulaEngine.ts): `src/utils/formulaEngine.ts`
- [Table cell logic](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/tableCells.ts): `src/utils/tableCells.ts`
- [Character presets](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/presets/index.ts): `src/presets/index.ts`
- [Timeline history](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useTimelineStore.ts): `src/store/useTimelineStore.ts`

### Storage and integrations

- [Workspace manager](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStorageWorkspaceStore.ts): `src/store/useStorageWorkspaceStore.ts`
- [Workspace registry](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/workspaceRegistry.ts): `src/workspaces/workspaceRegistry.ts`
- [Browser storage](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/browserWorkspaceProvider.ts): `src/workspaces/providers/browserWorkspaceProvider.ts`
- [Directory storage](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/directoryWorkspaceProvider.ts): `src/workspaces/providers/directoryWorkspaceProvider.ts`
- [Drive storage](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/providers/googleDriveWorkspaceProvider.ts): `src/workspaces/providers/googleDriveWorkspaceProvider.ts`
- [Google authorization](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/workspaces/google/googleClient.ts): `src/workspaces/google/googleClient.ts`
- [Storage warnings](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/components/StorageWarning.tsx): `src/components/StorageWarning.tsx`
- [Quota tracking](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/store/useStorageWarningStore.ts): `src/store/useStorageWarningStore.ts`
- [Storage monitor](https://github.com/wackyweasel/universalcharactersheet/blob/main/src/utils/storageMonitor.ts): `src/utils/storageMonitor.ts`

### Other components

- **Player**

## Connections

- Player → App shell: opens (evidence: `README.md`)
- App shell → Character state: reads state (evidence: `src/App.tsx`)
- App shell → Character manager: renders (evidence: `src/App.tsx`)
- App shell → Sheet canvas: renders (evidence: `src/App.tsx`)
- App shell → Dice physics: renders (evidence: `src/App.tsx`)
- App shell → Storage warnings: renders (evidence: `src/App.tsx`)
- App shell → Workspace manager: initializes (evidence: `src/App.tsx`)
- Sheet canvas → Widget arrangement: arranges widgets
- Widget arrangement → Character state: updates sheet (evidence: `src/components/DraggableWidget.tsx`)
- Widget arrangement → Widget experiences: renders widgets (evidence: `src/components/DraggableWidget.tsx`)
- Widget experiences → Character state: updates data (evidence: `src/components/widgets/CheckboxWidget.tsx`)
- Dice tools → Character state: updates rolls (evidence: `src/components/widgets/DiceRollerWidget.tsx`)
- Dice tools → Dice physics: uses physics (evidence: `src/components/widgets/DiceRollerWidget.tsx`)
- Table editor → Formula engine: evaluates formulas (evidence: `src/components/widgets/TableWidget.tsx`)
- Table editor → Table cell logic: uses cell logic (evidence: `src/components/widgets/TableWidget.tsx`)
- Formula display → Formula engine: displays formulas
- Character state → Formula engine: resolves formulas (evidence: `src/store/useStore.ts`)
- Character state → Character presets: loads presets (evidence: `src/store/useStore.ts`)
- Timeline history → Character state: reads character (evidence: `src/store/useTimelineStore.ts`)
- Workspace manager → Character state: coordinates data (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Workspace manager → Workspace registry: selects provider (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Workspace manager → Browser storage: loads and saves (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Workspace manager → Directory storage: creates and loads (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Workspace manager → Drive storage: uses provider (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Workspace manager → Google authorization: authorizes access (evidence: `src/store/useStorageWorkspaceStore.ts`)
- Storage warnings → Quota tracking: shows status (evidence: `src/components/StorageWarning.tsx`)
- Quota tracking → Storage monitor: checks quota (evidence: `src/store/useStorageWarningStore.ts`)
- Player → Offline support: installs app (evidence: `README.md`)
