# poli0981/frameledger architecture

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

- Interactive diagram: https://gitdiagram.com/poli0981/frameledger
- Repository: https://github.com/poli0981/frameledger

## Overview

FrameLedger is a local-first Windows game-performance ledger. The user adds or imports games, launches or plays them, and the background Agent records eligible sessions; the desktop app then presents session history and comparisons as charts and supports export. Distinct product stages include library management and detection, safety/consent gating, capture and telemetry, local persistence, and analysis. The README documents the main workflow and measured capabilities; sampled source confirms selected Agent, persistence, and export details, so unsampled feature links are limited to documented relationships.

Main entry points: [`src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs`](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs) (Session records), [`src/FrameLedger.Agent/Program.cs`](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Agent/Program.cs) (Background Agent), [`src/FrameLedger.Application/Capture`](https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/Capture) (Session capture), [`src/FrameLedger.Application/Persistence/GameRow.cs`](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Application/Persistence/GameRow.cs) (Game records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library and launch"]
  node_desktop["Desktop app<br/>[App.xaml.cs]"]
  node_libraryui["Game library<br/>[GamesPage.xaml.cs]"]
  node_storeimport["Store import"]
  node_detection["Game detection"]
end

subgraph group_capture["Safe capture"]
  node_agent["Background Agent<br/>[Program.cs]"]
  node_safety["Safety and consent<br/>[AntiCheat]"]
  node_captureflow["Session capture<br/>[Capture]"]
  node_telemetry["Performance telemetry<br/>[AdvancedProbe.cs]"]
end

subgraph group_storage["Local ledger"]
  node_consent[("Consent records")]
  node_games[("Game records<br/>[GameRow.cs]")]
  node_sessions[("Session records")]
  node_ledger[("SQLite ledger<br/>[LedgerDatabase.cs]")]
end

subgraph group_analysis["Review and analysis"]
  node_advanced["Advanced metrics<br/>[Advanced]"]
  node_dashboard["Dashboard"]
  node_charts["Session charts"]
  node_compare["Session comparison"]
  node_advancedview["Advanced review"]
  node_export["Session export"]
end

subgraph group_appops["App services"]
  node_settings["Settings and safety UI"]
  node_updates["App updates<br/>[UpdateService.cs]"]
end

node_user(("Player"))
node_game["Tracked game"]
node_externalstore["Game stores"]

node_user -->|"uses"| node_desktop
node_user -->|"manages games"| node_libraryui
node_externalstore -->|"provides library"| node_storeimport
node_storeimport -->|"imports games"| node_games
node_libraryui -->|"selects game"| node_game
node_detection -->|"updates metadata"| node_games
node_agent -->|"watches library"| node_games
node_agent -->|"checks capture safety"| node_safety
node_agent -->|"records session"| node_captureflow
node_captureflow -->|"collects metrics"| node_telemetry
node_captureflow -->|"writes session"| node_sessions
node_safety -->|"checks consent"| node_consent
node_sessions -->|"persists through"| node_ledger
node_user -->|"reviews history"| node_dashboard
node_dashboard -->|"reads history"| node_sessions
node_sessions -->|"supplies session data"| node_charts
node_charts -->|"supports comparison"| node_compare
node_sessions -->|"stores telemetry"| node_advanced
node_advanced -->|"feeds review"| node_advancedview
node_sessions -->|"provides export data"| node_export
node_user -->|"configures safety"| node_settings
node_desktop -.->|"checks updates"| node_updates

click node_desktop "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/App.xaml.cs"
click node_libraryui "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/GamesPage.xaml.cs"
click node_storeimport "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Services/ImportLibraryFlow.cs"
click node_detection "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Agent/Hosting/DetectionHostedService.cs"
click node_agent "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Agent/Program.cs"
click node_safety "https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/AntiCheat"
click node_captureflow "https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/Capture"
click node_telemetry "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.CaptureHost/Telemetry/AdvancedProbe.cs"
click node_advanced "https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/Advanced"
click node_consent "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/SqliteGameConsentStore.cs"
click node_games "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Application/Persistence/GameRow.cs"
click node_sessions "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs"
click node_ledger "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/LedgerDatabase.cs"
click node_dashboard "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/DashboardPage.xaml.cs"
click node_charts "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Charts/SessionSeriesLoader.cs"
click node_compare "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/ComparePage.xaml.cs"
click node_advancedview "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/AdvancedPage.xaml.cs"
click node_export "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Services/SessionExportService.cs"
click node_settings "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/SettingsPage.xaml.cs"
click node_updates "https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Update/UpdateService.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_desktop,node_libraryui,node_storeimport,node_detection toneBlue
class node_agent,node_safety,node_captureflow,node_telemetry toneAmber
class node_consent,node_games,node_sessions,node_ledger toneMint
class node_advanced,node_dashboard,node_charts,node_compare,node_advancedview,node_export toneRose
class node_settings,node_updates,node_user,node_game,node_externalstore toneIndigo
```

## Components

### Library and launch

- [Desktop app](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/App.xaml.cs): `src/FrameLedger.App/App.xaml.cs`
- [Game library](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/GamesPage.xaml.cs): `src/FrameLedger.App/Pages/GamesPage.xaml.cs`
- [Store import](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Services/ImportLibraryFlow.cs): `src/FrameLedger.App/Services/ImportLibraryFlow.cs`
- [Game detection](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Agent/Hosting/DetectionHostedService.cs): `src/FrameLedger.Agent/Hosting/DetectionHostedService.cs`

### Safe capture

- [Background Agent](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Agent/Program.cs): `src/FrameLedger.Agent/Program.cs`
- [Safety and consent](https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/AntiCheat): `src/FrameLedger.Application/AntiCheat`
- [Session capture](https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/Capture): `src/FrameLedger.Application/Capture`
- [Performance telemetry](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.CaptureHost/Telemetry/AdvancedProbe.cs): `src/FrameLedger.CaptureHost/Telemetry/AdvancedProbe.cs`

### Local ledger

- [Consent records](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/SqliteGameConsentStore.cs): `src/FrameLedger.Infrastructure/Persistence/SqliteGameConsentStore.cs`
- [Game records](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Application/Persistence/GameRow.cs): `src/FrameLedger.Application/Persistence/GameRow.cs`
- [Session records](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs): `src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs`
- [SQLite ledger](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.Infrastructure/Persistence/LedgerDatabase.cs): `src/FrameLedger.Infrastructure/Persistence/LedgerDatabase.cs`

### Review and analysis

- [Advanced metrics](https://github.com/poli0981/frameledger/tree/main/src/FrameLedger.Application/Advanced): `src/FrameLedger.Application/Advanced`
- [Dashboard](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/DashboardPage.xaml.cs): `src/FrameLedger.App/Pages/DashboardPage.xaml.cs`
- [Session charts](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Charts/SessionSeriesLoader.cs): `src/FrameLedger.App/Charts/SessionSeriesLoader.cs`
- [Session comparison](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/ComparePage.xaml.cs): `src/FrameLedger.App/Pages/ComparePage.xaml.cs`
- [Advanced review](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/AdvancedPage.xaml.cs): `src/FrameLedger.App/Pages/AdvancedPage.xaml.cs`
- [Session export](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Services/SessionExportService.cs): `src/FrameLedger.App/Services/SessionExportService.cs`

### App services

- [Settings and safety UI](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Pages/SettingsPage.xaml.cs): `src/FrameLedger.App/Pages/SettingsPage.xaml.cs`
- [App updates](https://github.com/poli0981/frameledger/blob/main/src/FrameLedger.App/Update/UpdateService.cs): `src/FrameLedger.App/Update/UpdateService.cs`

### Other components

- **Player**
- **Tracked game**
- **Game stores**

## Connections

- Player → Desktop app: uses (evidence: `README.md`)
- Player → Game library: manages games (evidence: `README.md`)
- Game stores → Store import: provides library (evidence: `README.md`)
- Store import → Game records: imports games (evidence: `README.md`)
- Game library → Tracked game: selects game (evidence: `README.md`)
- Game detection → Game records: updates metadata (evidence: `src/FrameLedger.Agent/Hosting/DetectionHostedService.cs`)
- Background Agent → Game records: watches library (evidence: `src/FrameLedger.Agent/Program.cs`)
- Background Agent → Safety and consent: checks capture safety (evidence: `README.md`)
- Background Agent → Session capture: records session (evidence: `src/FrameLedger.Agent/Program.cs`)
- Session capture → Performance telemetry: collects metrics (evidence: `README.md`)
- Session capture → Session records: writes session (evidence: `README.md`)
- Safety and consent → Consent records: checks consent (evidence: `README.md`)
- Session records → SQLite ledger: persists through (evidence: `src/FrameLedger.Infrastructure/Persistence/SqliteSessionRepository.cs`)
- Player → Dashboard: reviews history (evidence: `README.md`)
- Dashboard → Session records: reads history (evidence: `README.md`)
- Session records → Session charts: supplies session data
- Session charts → Session comparison: supports comparison (evidence: `README.md`)
- Session records → Advanced metrics: stores telemetry (evidence: `README.md`)
- Advanced metrics → Advanced review: feeds review (evidence: `README.md`)
- Session records → Session export: provides export data (evidence: `src/FrameLedger.App/Services/SessionExportService.cs`)
- Player → Settings and safety UI: configures safety (evidence: `README.md`)
- Desktop app → App updates: checks updates
