# bariskisir/sessionlens architecture

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

- Interactive diagram: https://gitdiagram.com/bariskisir/sessionlens
- Repository: https://github.com/bariskisir/sessionlens

## Overview

Session Lens is an Electron desktop app for monitoring AI-provider usage limits. Its main workflow is: the main process loads settings, periodically queries enabled providers, aggregates quota windows, then updates the tray icon and tooltip, emits snapshots, and checks notification thresholds. Users configure providers and display behavior in the renderer; settings cross a limited preload IPC bridge and persist as validated JSON. The README also documents reset-window warm starts, update checks, and multiple notification channels. Wiring beyond the sampled excerpts is shown only where the tree or documentation supports the subsystem; those paths identify enclosing directories.

Main entry points: [`src/main/services/usage/UsageRefreshService.ts`](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageRefreshService.ts) (Refresh service), [`src/main/index.ts`](https://github.com/bariskisir/sessionlens/blob/master/src/main/index.ts) (App lifecycle), [`src/main/ipc.ts`](https://github.com/bariskisir/sessionlens/blob/master/src/main/ipc.ts) (IPC handlers), [`src/preload/index.ts`](https://github.com/bariskisir/sessionlens/blob/master/src/preload/index.ts) (Preload API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop runtime"]
  node_main["App lifecycle<br/>[index.ts]"]
  node_window["Window service<br/>[WindowService.ts]"]
  node_ipc["IPC handlers<br/>[ipc.ts]"]
  node_preload["Preload API<br/>[index.ts]"]
  node_tray["Tray and tooltip<br/>[TrayService.ts]"]
end

subgraph group_usage["Usage monitoring"]
  node_refresh["Refresh service"]
  node_aggregate["Usage aggregator<br/>[UsageAggregator.ts]"]
  node_providers["Usage providers"]
  node_auth["Auth readers"]
  node_format["Usage presentation"]
  node_notifications["Threshold notifications"]
  node_warm["Window warm starts"]
end

subgraph group_interface["Renderer interface"]
  node_renderer["Settings interface<br/>[App.tsx]"]
  node_settings["Settings actions"]
  node_store["Renderer state"]
end

subgraph group_settings["Settings and state"]
  node_storage[("Settings storage<br/>[StorageService.ts]")]
end

subgraph group_integrations["External integrations"]
  node_updater["Update service<br/>[AppUpdater.ts]"]
  node_telemetry["Telemetry service"]
  node_providerapis(("Provider APIs"))
  node_notifier(("Notification channels"))
  node_github(("GitHub Releases"))
end

node_user(("Desktop user"))

node_user -->|"configures"| node_renderer
node_main -->|"loads settings"| node_storage
node_main -->|"creates window"| node_window
node_main -->|"starts loop"| node_refresh
node_main -->|"registers handlers"| node_ipc
node_main -->|"tracks startup"| node_telemetry
node_renderer -->|"calls API"| node_preload
node_preload -->|"invokes channels"| node_ipc
node_ipc -->|"reads and saves"| node_storage
node_ipc -->|"requests refresh"| node_refresh
node_refresh -->|"loads settings"| node_storage
node_refresh -->|"queries usage"| node_aggregate
node_aggregate -->|"dispatches queries"| node_providers
node_providers -->|"requests quotas"| node_providerapis
node_aggregate -->|"uses credentials"| node_auth
node_refresh -->|"sets usage display"| node_tray
node_refresh -->|"builds display data"| node_format
node_refresh -->|"checks thresholds"| node_notifications
node_notifications -->|"sends alerts"| node_notifier
node_refresh -->|"observes windows"| node_warm
node_tray -->|"shows status"| node_user
node_refresh -->|"emits snapshots"| node_ipc
node_ipc -->|"forwards events"| node_preload
node_preload -->|"delivers updates"| node_renderer
node_settings -->|"saves settings"| node_preload
node_settings -->|"updates state"| node_store
node_main -->|"creates service"| node_updater
node_updater -->|"checks releases"| node_github

click node_main "https://github.com/bariskisir/sessionlens/blob/master/src/main/index.ts"
click node_window "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/WindowService.ts"
click node_ipc "https://github.com/bariskisir/sessionlens/blob/master/src/main/ipc.ts"
click node_preload "https://github.com/bariskisir/sessionlens/blob/master/src/preload/index.ts"
click node_refresh "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageRefreshService.ts"
click node_aggregate "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageAggregator.ts"
click node_providers "https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage/providers"
click node_auth "https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage"
click node_format "https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage"
click node_tray "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/TrayService.ts"
click node_notifications "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/NotificationDispatcher.ts"
click node_warm "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageWindowStartService.ts"
click node_renderer "https://github.com/bariskisir/sessionlens/blob/master/src/renderer/src/App.tsx"
click node_settings "https://github.com/bariskisir/sessionlens/blob/master/src/renderer/src/hooks/useSettingsActions.ts"
click node_store "https://github.com/bariskisir/sessionlens/tree/master/src/renderer/src/store"
click node_storage "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/StorageService.ts"
click node_updater "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/AppUpdater.ts"
click node_telemetry "https://github.com/bariskisir/sessionlens/blob/master/src/main/services/TelemetryService.ts"

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_main,node_window,node_ipc,node_preload,node_tray,node_user toneBlue
class node_refresh,node_aggregate,node_providers,node_auth,node_format,node_notifications,node_warm toneAmber
class node_renderer,node_settings,node_store toneMint
class node_storage toneRose
class node_updater,node_telemetry,node_providerapis,node_notifier,node_github toneIndigo
```

## Components

### Desktop runtime

- [App lifecycle](https://github.com/bariskisir/sessionlens/blob/master/src/main/index.ts): `src/main/index.ts`
- [Window service](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/WindowService.ts): `src/main/services/WindowService.ts`
- [IPC handlers](https://github.com/bariskisir/sessionlens/blob/master/src/main/ipc.ts): `src/main/ipc.ts`
- [Preload API](https://github.com/bariskisir/sessionlens/blob/master/src/preload/index.ts): `src/preload/index.ts`
- [Tray and tooltip](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/TrayService.ts): `src/main/services/TrayService.ts`

### Usage monitoring

- [Refresh service](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageRefreshService.ts): `src/main/services/usage/UsageRefreshService.ts`
- [Usage aggregator](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageAggregator.ts): `src/main/services/usage/UsageAggregator.ts`
- [Usage providers](https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage/providers): `src/main/services/usage/providers`
- [Auth readers](https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage): `src/main/services/usage`
- [Usage presentation](https://github.com/bariskisir/sessionlens/tree/master/src/main/services/usage): `src/main/services/usage`
- [Threshold notifications](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/NotificationDispatcher.ts): `src/main/services/usage/NotificationDispatcher.ts`
- [Window warm starts](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/usage/UsageWindowStartService.ts): `src/main/services/usage/UsageWindowStartService.ts`

### Renderer interface

- [Settings interface](https://github.com/bariskisir/sessionlens/blob/master/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Settings actions](https://github.com/bariskisir/sessionlens/blob/master/src/renderer/src/hooks/useSettingsActions.ts): `src/renderer/src/hooks/useSettingsActions.ts`
- [Renderer state](https://github.com/bariskisir/sessionlens/tree/master/src/renderer/src/store): `src/renderer/src/store`

### Settings and state

- [Settings storage](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/StorageService.ts): `src/main/services/StorageService.ts`

### External integrations

- [Update service](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/AppUpdater.ts): `src/main/services/AppUpdater.ts`
- [Telemetry service](https://github.com/bariskisir/sessionlens/blob/master/src/main/services/TelemetryService.ts): `src/main/services/TelemetryService.ts`
- **Provider APIs**
- **Notification channels**
- **GitHub Releases**

### Other components

- **Desktop user**

## Connections

- Desktop user → Settings interface: configures
- App lifecycle → Settings storage: loads settings
- App lifecycle → Window service: creates window
- App lifecycle → Refresh service: starts loop
- App lifecycle → IPC handlers: registers handlers
- App lifecycle → Telemetry service: tracks startup
- Settings interface → Preload API: calls API
- Preload API → IPC handlers: invokes channels
- IPC handlers → Settings storage: reads and saves
- IPC handlers → Refresh service: requests refresh
- Refresh service → Settings storage: loads settings
- Refresh service → Usage aggregator: queries usage
- Usage aggregator → Usage providers: dispatches queries
- Usage providers → Provider APIs: requests quotas
- Usage aggregator → Auth readers: uses credentials
- Refresh service → Tray and tooltip: sets usage display
- Refresh service → Usage presentation: builds display data
- Refresh service → Threshold notifications: checks thresholds
- Threshold notifications → Notification channels: sends alerts
- Refresh service → Window warm starts: observes windows
- Tray and tooltip → Desktop user: shows status
- Refresh service → IPC handlers: emits snapshots
- IPC handlers → Preload API: forwards events
- Preload API → Settings interface: delivers updates
- Settings actions → Preload API: saves settings
- Settings actions → Renderer state: updates state
- App lifecycle → Update service: creates service
- Update service → GitHub Releases: checks releases