# franciscobsalgueiro/en-croissant architecture

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

- Interactive diagram: https://gitdiagram.com/franciscobsalgueiro/en-croissant
- Repository: https://github.com/franciscobsalgueiro/en-croissant

## Overview

En-Croissant is a desktop application built as a Tauri shell around a React/TypeScript frontend and a Rust backend. The key architectural boundary is the Tauri bridge: the UI handles interaction and rendering, while Rust owns local system access, file/database operations, engine processes, and other privileged work.

The frontend is organized around route-level pages rather than a single screen. Main entry points include accounts, databases, engines, files, settings, and the home dashboard. The top-level app and route tree coordinate navigation, while most user-facing behavior is implemented in feature folders under `src/components`.

A large part of the UI is board-centric. The chessboard is rendered through a `chessground` wrapper, with surrounding panels for analysis, annotation, database lookup, practice, puzzle solving, and game info. This board workspace is the core interaction surface for reviewing positions, editing games, and driving engine analysis.

State is split between local UI state and durable app state. The `src/state` layer contains atoms, tree/session utilities, keybind definitions, and debounced storage, which suggests the app persists user preferences and workspace state locally. The `src/utils` layer contains most shared domain logic for chess, scoring, clocks, time controls, repertoire behavior, tabs, and session management.

The Rust backend under `src-tauri/src` is responsible for the non-UI subsystems. It includes modules for chess logic, PGN parsing, puzzle support, progress reporting, sound playback, file-system access, OAuth, and opening preparation. This backend likely exposes Tauri commands that the frontend calls for local processing and integrations.

Database handling is a major subsystem. The `src-tauri/src/db` module contains schema, models, operations, search, indexing, and encoding code, along with SQL files for creation and index maintenance. On the UI side, database pages and panels support viewing games, players, tournaments, and openings, plus database loading and source-specific options for local, Lichess, and Masters data.

Engine support is another primary boundary. The Rust `engine` module manages external UCI engines as processes, while the frontend provides engine selection, engine settings, analysis controls, and log views. The analysis workflow likely flows from the board state into engine commands, then back into evaluation, principal variation, and reporting UI.

External services are integrated through dedicated utilities and OAuth support. The repo includes Lichess and chess.com API helpers, a chess.com-specific TCN utility, and a chessdb API helper, indicating that online account/game import and position lookup are first-class features. These services feed the accounts and databases areas rather than being directly embedded in the board UI.

File and repertoire management is treated as a separate subsystem. The files pages and helpers manage local directories, file cards, and opening data, while the practice and repertoire panels use that data for training workflows. This makes the app useful both as a database browser and as a local study environment.

The app is heavily themeable and localized. Static assets include many chess piece sets and multiple sound packs, while translations are organized through `i18next` locale files. These assets affect diagramming because they are not just cosmetic: they are part of the configurable presentation layer and user experience.

Build and deployment are split between a web-tooling frontend and a native backend package. The frontend uses Vite, TypeScript, and pnpm, while the Rust side is built with Cargo under Tauri. GitHub Actions cover testing and release, and the repository also includes frontend tests for chess logic and store behavior.

For an architecture diagram, the clearest high-level flow is: user interaction in React pages and board panels → shared TypeScript domain/state utilities → Tauri command bridge → Rust services for filesystem, database, engines, and external access → results returned to the UI for rendering and persistence.

Main entry points: [`src/routes`](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/routes) (Route tree), [`src/components/settings`](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/settings) (Settings page), [`src-tauri/src/main.rs`](https://github.com/franciscobsalgueiro/en-croissant/blob/master/src-tauri/src/main.rs) (Rust backend), [`src-tauri/src`](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src) (Local services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app["App shell<br/>React app<br/>[App.tsx]"]
  node_routes["Route tree<br/>Navigation"]
  node_board["Board workspace<br/>Chess UI"]
  node_home["Home pages<br/>Dashboard"]
  node_databases["Database pages<br/>Data browser"]
  node_files["File pages<br/>File manager"]
  node_engines["Engine pages<br/>Engine setup"]
  node_settings["Settings page<br/>Preferences"]
  node_tabs["Tab workspaces<br/>Workspace UI"]
  node_bridge["Tauri bindings<br/>Bridge"]
end

subgraph group_state["State & Logic"]
  node_state[("App state<br/>Atoms/store")]
  node_utils["Domain utils<br/>Shared logic"]
end

subgraph group_backend["Backend"]
  node_tauri["Rust backend<br/>Native shell<br/>[main.rs]"]
  node_db[("Database core<br/>SQLite layer")]
  node_engine["Engine runner<br/>UCI processes"]
  node_services["Local services<br/>Backend modules"]
end

subgraph group_assets["Assets"]
  node_translations["Locales<br/>i18n"]
  node_pieces["Pieces & sounds<br/>Presentation assets"]
end

node_app -->|"navigates"| node_routes
node_routes -->|"renders"| node_home
node_routes -->|"renders"| node_databases
node_routes -->|"renders"| node_files
node_routes -->|"renders"| node_engines
node_routes -->|"renders"| node_settings
node_routes -->|"renders"| node_tabs
node_routes -->|"hosts"| node_board
node_board -->|"reads/writes"| node_state
node_board -->|"uses"| node_utils
node_tabs -->|"persists"| node_state
node_databases -->|"calls"| node_bridge
node_files -->|"calls"| node_bridge
node_engines -->|"calls"| node_bridge
node_settings -->|"persists"| node_state
node_settings -->|"configures"| node_pieces
node_settings -->|"uses"| node_translations
node_bridge -->|"invokes"| node_tauri
node_tauri -->|"owns"| node_db
node_tauri -->|"owns"| node_engine
node_tauri -->|"provides"| node_services
node_services -.->|"supports"| node_db
node_services -.->|"coordinates"| node_engine
node_utils -.->|"shapes data"| node_services

click node_app "https://github.com/franciscobsalgueiro/en-croissant/blob/master/src/App.tsx"
click node_routes "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/routes"
click node_board "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/boards"
click node_home "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/home"
click node_databases "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/databases"
click node_files "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/files"
click node_engines "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/engines"
click node_settings "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/settings"
click node_tabs "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/tabs"
click node_state "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/state"
click node_utils "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/utils"
click node_bridge "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/bindings"
click node_tauri "https://github.com/franciscobsalgueiro/en-croissant/blob/master/src-tauri/src/main.rs"
click node_db "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src/db"
click node_engine "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src/engine"
click node_services "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src"
click node_translations "https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/translation"
click node_pieces "https://github.com/franciscobsalgueiro/en-croissant/tree/master/public"

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_routes,node_board,node_home,node_databases,node_files,node_engines,node_settings,node_tabs,node_bridge toneBlue
class node_state,node_utils toneAmber
class node_tauri,node_db,node_engine,node_services toneMint
class node_translations,node_pieces toneRose
```

## Components

### Frontend

React/Tauri UI, routing, and feature components

- [App shell](https://github.com/franciscobsalgueiro/en-croissant/blob/master/src/App.tsx): React app · Top-level React entry and route wiring · `src/App.tsx`
- [Route tree](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/routes): Navigation · Route-level pages for accounts, databases, engines, files, settings, and home · `src/routes`
- [Board workspace](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/boards): Chess UI · Main chessboard surface and surrounding analysis/editing panels · `src/components/boards`
- [Home pages](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/home): Dashboard · Account and personal overview screens · `src/components/home`
- [Database pages](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/databases): Data browser · Database list, views, players, tournaments, and source options · `src/components/databases`
- [File pages](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/files): File manager · Local directories, file cards, and opening files · `src/components/files`
- [Engine pages](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/engines): Engine setup · Engine management and configuration screens · `src/components/engines`
- [Settings page](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/settings): Preferences · User preferences for board, sound, theme, and keybinds · `src/components/settings`
- [Tab workspaces](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/components/tabs): Workspace UI · Board tabs, new-tab home, import, and repertoire flows · `src/components/tabs`
- [Tauri bindings](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/bindings): Bridge · Generated command bindings used by the frontend to call Rust · `src/bindings`

### State & Logic

Shared TypeScript state and domain utilities

- [App state](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/state): Atoms/store · Persistent UI state, tree/session utilities, and debounced storage · `src/state`
- [Domain utils](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/utils): Shared logic · Chess, scoring, clocks, repertoire, files, tabs, and session helpers · `src/utils`

### Backend

Rust services behind the Tauri bridge

- [Rust backend](https://github.com/franciscobsalgueiro/en-croissant/blob/master/src-tauri/src/main.rs): Native shell · Tauri application entry and command host · `src-tauri/src/main.rs`
- [Database core](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src/db): SQLite layer · Schema, models, search, indexing, and SQL maintenance · `src-tauri/src/db`
- [Engine runner](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src/engine): UCI processes · External chess engine process management and UCI protocol handling · `src-tauri/src/engine`
- [Local services](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src-tauri/src): Backend modules · Chess logic, PGN, puzzles, opening prep, filesystem, OAuth, progress, and sound · `src-tauri/src`

### Assets

Static presentation assets and localization

- [Locales](https://github.com/franciscobsalgueiro/en-croissant/tree/master/src/translation): i18n · Application translation bundles · `src/translation`
- [Pieces & sounds](https://github.com/franciscobsalgueiro/en-croissant/tree/master/public): Presentation assets · Chess piece themes and move sound packs · `public`

## Connections

- App shell → Route tree: navigates · App shell mounts the route tree
- Route tree → Home pages: renders · Routes open dashboard and account pages
- Route tree → Database pages: renders · Routes open database browsing pages
- Route tree → File pages: renders · Routes open file management pages
- Route tree → Engine pages: renders · Routes open engine configuration pages
- Route tree → Settings page: renders · Routes open settings pages
- Route tree → Tab workspaces: renders · Routes support board workspace and tab flows
- Route tree → Board workspace: hosts · Route-level pages embed the board workspace
- Board workspace → App state: reads/writes · Board interaction is coordinated through app state
- Board workspace → Domain utils: uses · Board logic relies on shared chess and session helpers
- Tab workspaces → App state: persists · Workspace/tab state is stored locally
- Database pages → Tauri bindings: calls · Database UI invokes Tauri commands through bindings
- File pages → Tauri bindings: calls · File UI accesses local filesystem through bindings
- Engine pages → Tauri bindings: calls · Engine UI configures and monitors backend processes
- Settings page → App state: persists · Preferences are stored through the state layer
- Settings page → Pieces & sounds: configures · Theme settings affect board pieces and sounds
- Settings page → Locales: uses · Localized strings drive the settings UI
- Tauri bindings → Rust backend: invokes · Generated bindings call into Rust commands
- Rust backend → Database core: owns · Backend manages database creation, search, and indexing
- Rust backend → Engine runner: owns · Backend launches and supervises external engines
- Rust backend → Local services: provides · Backend exposes filesystem, chess, PGN, OAuth, puzzle, and sound services
- Local services → Database core: supports · Local services feed database and opening workflows
- Local services → Engine runner: coordinates · Analysis and puzzle flows coordinate with engine processes
- Domain utils → Local services: shapes data · Frontend domain objects align with backend service behavior
