# solis-syst/solis-app-v4 architecture

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

- Interactive diagram: https://gitdiagram.com/solis-syst/solis-app-v4
- Repository: https://github.com/solis-syst/solis-app-v4

## Overview

Solis is an Avalonia desktop chess-browser assistant: users authenticate, open chess sites in browser tabs, and receive board-aware engine and opening-book analysis, with configurable coaching and move assistance. The native WebView bridge connects the desktop UI to a locally hosted chess runtime; the runtime includes board integration, engine workers, and bundled models. Authentication and session persistence are visible in sampled source. Runtime paths and several documented capabilities are represented from the tree, but their internal wiring is not fully sampled, so uncertain links are omitted.

Main entry points: [`Services/WebViewBridgeService.cs`](https://github.com/solis-syst/solis-app-v4/blob/main/Services/WebViewBridgeService.cs) (WebView bridge), [`Views/MainWindow.axaml.cs`](https://github.com/solis-syst/solis-app-v4/blob/main/Views/MainWindow.axaml.cs) (Chess browser), [`Services/SupabaseAuthService.cs`](https://github.com/solis-syst/solis-app-v4/blob/main/Services/SupabaseAuthService.cs) (Supabase auth), [`App.axaml.cs`](https://github.com/solis-syst/solis-app-v4/blob/main/App.axaml.cs) (App lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_app["App lifecycle<br/>[App.axaml.cs]"]
  node_mainview["Chess browser"]
  node_loginview["Login view"]
  node_loginvm["Login state<br/>[LoginViewModel.cs]"]
  node_assistantvm["Assistant state"]
  node_updater["Velopack updater<br/>[App.axaml.cs]"]
end

subgraph group_identity["Authentication"]
  node_auth["Supabase auth"]
  node_session["Session persistence"]
  node_activation["URI activation"]
end

subgraph group_bridge["Browser bridge"]
  node_bridge["WebView bridge"]
  node_localhost["Local runtime host"]
end

subgraph group_chess["Chess runtime"]
  node_pagebridge["Page bridge<br/>[page-bridge.js]"]
  node_loader["Runtime loader<br/>[bridge-loader.js]"]
  node_board["Chess board UI<br/>[board.html]"]
  node_boardjs["Board logic<br/>[board.js]"]
  node_content["Runtime content"]
  node_coach["Coach controller"]
  node_worker["Engine worker"]
  node_engines["Bundled engines"]
  node_maia["Maia model"]
  node_bookdata["Opening book data<br/>[book.bin]"]
end

subgraph group_analysis["Analysis services"]
  node_book["Opening book service"]
  node_catalog["Engine and coach catalog"]
  node_engineconfig["Engine settings model"]
end

node_user(("Chess user"))
node_supabase["Supabase"]
node_oauth(("System browser"))
node_webpage(("Chess site tabs"))
node_releases["GitHub Releases"]

node_user -->|"signs in"| node_loginview
node_loginview -->|"binds input"| node_loginvm
node_loginvm -->|"requests auth"| node_auth
node_auth -->|"authenticates"| node_supabase
node_auth -->|"persists session"| node_session
node_oauth -->|"returns callback"| node_activation
node_activation -->|"dispatches URI"| node_app
node_app -->|"initializes"| node_auth
node_app -->|"opens after auth"| node_mainview
node_user -->|"uses browser"| node_mainview
node_mainview -->|"attaches WebView"| node_bridge
node_mainview -->|"presents state"| node_assistantvm
node_bridge -->|"updates analysis"| node_assistantvm
node_bridge -->|"requests lookup"| node_book
node_book -->|"reads book"| node_bookdata
node_bridge -->|"serves runtime"| node_localhost
node_webpage -->|"hosts integration"| node_pagebridge
node_loader -->|"loads runtime"| node_content
node_content -->|"provides board"| node_board
node_board -->|"runs board logic"| node_boardjs
node_content -->|"coordinates coaching"| node_coach
node_worker -->|"loads engine assets"| node_engines
node_worker -->|"loads model data"| node_maia
node_assistantvm -->|"exposes choices"| node_catalog
node_catalog -->|"uses definitions"| node_engineconfig
node_updater -.->|"checks updates"| node_releases

click node_app "https://github.com/solis-syst/solis-app-v4/blob/main/App.axaml.cs"
click node_mainview "https://github.com/solis-syst/solis-app-v4/blob/main/Views/MainWindow.axaml.cs"
click node_loginview "https://github.com/solis-syst/solis-app-v4/blob/main/Views/LoginWindow.axaml.cs"
click node_loginvm "https://github.com/solis-syst/solis-app-v4/blob/main/ViewModels/LoginViewModel.cs"
click node_assistantvm "https://github.com/solis-syst/solis-app-v4/blob/main/ViewModels/LiveAssistantViewModel.cs"
click node_auth "https://github.com/solis-syst/solis-app-v4/blob/main/Services/SupabaseAuthService.cs"
click node_session "https://github.com/solis-syst/solis-app-v4/blob/main/Services/SupabaseAuthService.cs"
click node_activation "https://github.com/solis-syst/solis-app-v4/blob/main/Services/SingleInstanceActivationService.cs"
click node_bridge "https://github.com/solis-syst/solis-app-v4/blob/main/Services/WebViewBridgeService.cs"
click node_localhost "https://github.com/solis-syst/solis-app-v4/blob/main/Services/LocalRuntimeHost.cs"
click node_pagebridge "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/page-bridge.js"
click node_loader "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/bridge-loader.js"
click node_board "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/board.html"
click node_boardjs "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/board.js"
click node_content "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-content.js"
click node_coach "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-coach-controller.js"
click node_worker "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-engine-worker.js"
click node_engines "https://github.com/solis-syst/solis-app-v4/tree/main/ChessRuntime/lib"
click node_maia "https://github.com/solis-syst/solis-app-v4/tree/main/ChessRuntime/lib/maia3"
click node_book "https://github.com/solis-syst/solis-app-v4/blob/main/Services/PolyglotBookService.cs"
click node_bookdata "https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/book/book.bin"
click node_catalog "https://github.com/solis-syst/solis-app-v4/blob/main/Services/ChessConfigurationCatalog.cs"
click node_engineconfig "https://github.com/solis-syst/solis-app-v4/blob/main/Models/EngineDefinition.cs"
click node_updater "https://github.com/solis-syst/solis-app-v4/blob/main/App.axaml.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_app,node_mainview,node_loginview,node_loginvm,node_assistantvm,node_updater,node_user,node_oauth toneBlue
class node_auth,node_session,node_activation toneAmber
class node_bridge,node_localhost toneMint
class node_pagebridge,node_loader,node_board,node_boardjs,node_content,node_coach,node_worker,node_engines,node_maia,node_bookdata toneRose
class node_book,node_catalog,node_engineconfig,node_supabase,node_webpage,node_releases toneIndigo
```

## Components

### Desktop app

- [App lifecycle](https://github.com/solis-syst/solis-app-v4/blob/main/App.axaml.cs): `App.axaml.cs`
- [Chess browser](https://github.com/solis-syst/solis-app-v4/blob/main/Views/MainWindow.axaml.cs): `Views/MainWindow.axaml.cs`
- [Login view](https://github.com/solis-syst/solis-app-v4/blob/main/Views/LoginWindow.axaml.cs): `Views/LoginWindow.axaml.cs`
- [Login state](https://github.com/solis-syst/solis-app-v4/blob/main/ViewModels/LoginViewModel.cs): `ViewModels/LoginViewModel.cs`
- [Assistant state](https://github.com/solis-syst/solis-app-v4/blob/main/ViewModels/LiveAssistantViewModel.cs): `ViewModels/LiveAssistantViewModel.cs`
- [Velopack updater](https://github.com/solis-syst/solis-app-v4/blob/main/App.axaml.cs): `App.axaml.cs`

### Authentication

- [Supabase auth](https://github.com/solis-syst/solis-app-v4/blob/main/Services/SupabaseAuthService.cs): `Services/SupabaseAuthService.cs`
- [Session persistence](https://github.com/solis-syst/solis-app-v4/blob/main/Services/SupabaseAuthService.cs): `Services/SupabaseAuthService.cs`
- [URI activation](https://github.com/solis-syst/solis-app-v4/blob/main/Services/SingleInstanceActivationService.cs): `Services/SingleInstanceActivationService.cs`

### Browser bridge

- [WebView bridge](https://github.com/solis-syst/solis-app-v4/blob/main/Services/WebViewBridgeService.cs): `Services/WebViewBridgeService.cs`
- [Local runtime host](https://github.com/solis-syst/solis-app-v4/blob/main/Services/LocalRuntimeHost.cs): `Services/LocalRuntimeHost.cs`

### Chess runtime

- [Page bridge](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/page-bridge.js): `ChessRuntime/page-bridge.js`
- [Runtime loader](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/bridge-loader.js): `ChessRuntime/bridge-loader.js`
- [Chess board UI](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/board.html): `ChessRuntime/board.html`
- [Board logic](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/board.js): `ChessRuntime/board.js`
- [Runtime content](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-content.js): `ChessRuntime/refactored-content.js`
- [Coach controller](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-coach-controller.js): `ChessRuntime/refactored-coach-controller.js`
- [Engine worker](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/refactored-engine-worker.js): `ChessRuntime/refactored-engine-worker.js`
- [Bundled engines](https://github.com/solis-syst/solis-app-v4/tree/main/ChessRuntime/lib): `ChessRuntime/lib`
- [Maia model](https://github.com/solis-syst/solis-app-v4/tree/main/ChessRuntime/lib/maia3): `ChessRuntime/lib/maia3`
- [Opening book data](https://github.com/solis-syst/solis-app-v4/blob/main/ChessRuntime/book/book.bin): `ChessRuntime/book/book.bin`

### Analysis services

- [Opening book service](https://github.com/solis-syst/solis-app-v4/blob/main/Services/PolyglotBookService.cs): `Services/PolyglotBookService.cs`
- [Engine and coach catalog](https://github.com/solis-syst/solis-app-v4/blob/main/Services/ChessConfigurationCatalog.cs): `Services/ChessConfigurationCatalog.cs`
- [Engine settings model](https://github.com/solis-syst/solis-app-v4/blob/main/Models/EngineDefinition.cs): `Models/EngineDefinition.cs`

### Other components

- **Chess user**
- **Supabase**
- **System browser**
- **Chess site tabs**
- **GitHub Releases**

## Connections

- Chess user → Login view: signs in
- Login view → Login state: binds input
- Login state → Supabase auth: requests auth
- Supabase auth → Supabase: authenticates
- Supabase auth → Session persistence: persists session
- System browser → URI activation: returns callback
- URI activation → App lifecycle: dispatches URI
- App lifecycle → Supabase auth: initializes
- App lifecycle → Chess browser: opens after auth
- Chess user → Chess browser: uses browser
- Chess browser → WebView bridge: attaches WebView
- Chess browser → Assistant state: presents state
- WebView bridge → Assistant state: updates analysis
- WebView bridge → Opening book service: requests lookup
- Opening book service → Opening book data: reads book
- WebView bridge → Local runtime host: serves runtime
- Chess site tabs → Page bridge: hosts integration
- Runtime loader → Runtime content: loads runtime
- Runtime content → Chess board UI: provides board
- Chess board UI → Board logic: runs board logic
- Runtime content → Coach controller: coordinates coaching
- Engine worker → Bundled engines: loads engine assets
- Engine worker → Maia model: loads model data
- Assistant state → Engine and coach catalog: exposes choices
- Engine and coach catalog → Engine settings model: uses definitions
- Velopack updater → GitHub Releases: checks updates