Technical Architecture

​

Technology Stack

​

Frontend Technologies

• React 19 - UI framework with React Compiler optimization
• TypeScript - Type-safe development
• Vite - Fast build tool and development server
• TanStack Router - Type-safe file-based routing
• Mantine UI - Component library for consistent design
• Jotai - Atomic state management
• Chessground - Lichess’s chess board component

​

Backend Technologies

• Tauri 2.x - Cross-platform application framework
• Tokio - Async runtime for concurrent operations
• Diesel - Type-safe database ORM with SQLite
• Shakmaty - Chess logic and move validation
• pgn-reader - Fast PGN file parsing
• vampirc-uci - UCI protocol for chess engine communication

​

Frontend Architecture

​

Routing

​

State Management

• src/state/atoms.ts - Global application atoms
• src/state/keybinds.ts - Keyboard shortcut configuration
• src/state/store/ - Specialized state stores

​

Component Structure

src/components/
├── boards/        # Chess board components
├── common/        # Shared UI components
├── databases/     # Database management UI
├── engines/       # Engine configuration UI
├── files/         # File browser and management
├── home/          # Home screen components
├── panels/        # Analysis panels and sidebars
├── puzzles/       # Puzzle training UI
├── settings/      # Application settings
└── tabs/          # Tab management

​

Styling

​

Backend Architecture

​

Rust Module Structure

src-tauri/src/
├── main.rs        # Application entry point, Tauri setup
├── chess.rs       # Engine analysis and best moves
├── db/            # Database operations
│   ├── mod.rs     # Database connection management
│   ├── ops.rs     # CRUD operations
│   ├── search.rs  # Position and game search
│   ├── models.rs  # Data models
│   └── schema.rs  # Database schema
├── engine/        # Chess engine integration
│   ├── mod.rs     # Engine management
│   ├── process.rs # Engine process lifecycle
│   ├── uci.rs     # UCI protocol implementation
│   └── types.rs   # Engine data types
├── game.rs        # Game state and move validation
├── pgn.rs         # PGN file parsing and writing
├── opening.rs     # Opening database queries
├── puzzle.rs      # Puzzle database operations
├── fs.rs          # File system operations
├── oauth.rs       # OAuth authentication (Lichess/Chess.com)
└── error.rs       # Error handling

​

Database Layer

• Game storage and indexing
• Position search with custom encoding
• Player and tournament data
• Opening repertoires
• Puzzle databases

​

Engine Integration

1. Engine processes are spawned and managed in engine/process.rs
2. UCI commands are sent through engine/uci.rs
3. Analysis results are streamed to the frontend via Tauri events
4. Multiple engines can analyze simultaneously

​

Frontend-Backend Communication

​

Tauri Commands

// Frontend (TypeScript)
import { commands } from '@/bindings/generated'

const games = await commands.getGames({
  path: databasePath,
  query: { /* ... */ }
})

// Backend (Rust)
#[tauri::command]
#[specta::specta]
async fn get_games(
    path: String,
    query: GameQuery,
    state: State<'_, AppState>,
) -> Result<Vec<NormalizedGame>, String> {
    // Implementation
}

​

Type Generation

​

Event System

• BestMovesPayload - Engine analysis updates
• DatabaseProgress - Long-running database operations
• GameMoveEvent - Game state changes
• ClockUpdateEvent - Chess clock updates

​

Key Design Decisions

​

Why Tauri?

• Small bundle size - 5-10MB compared to 100MB+ Electron apps
• Native performance - Rust backend for heavy computation
• System integration - Direct file system and process access
• Security - Rust’s memory safety and explicit API exposure

​

Why Rust for the Backend?

• Performance - Critical for analyzing thousands of games
• Concurrency - Tokio enables efficient async operations
• Safety - Memory safety prevents crashes
• Chess libraries - Excellent chess ecosystem (shakmaty, pgn-reader)

​

State Management with Jotai

• Atomic updates - Fine-grained reactivity
• TypeScript support - First-class type inference
• Minimal boilerplate - Simpler than Redux
• React Suspense integration - Async state handling

​

Database: SQLite

• Serverless - No separate database process
• Portable - Single file databases
• Fast - Optimized for local queries
• Reliable - Battle-tested and stable

​

Performance Optimizations

​

Frontend

• React Compiler - Automatic memoization
• Virtual scrolling - Efficient rendering of large game lists
• Code splitting - Route-based lazy loading
• Vanilla Extract - Zero-runtime CSS

​

Backend

• Connection pooling - Reuse database connections
• Async I/O - Non-blocking file and network operations
• Memory-mapped files - Fast position search index
• Rayon - Parallel processing for batch operations
• Custom encoding - Compact position representation

​

Build System

​

Development

pnpm dev  # Starts Vite dev server + Tauri in dev mode

​

Production

pnpm build  # Builds optimized bundle

1. TypeScript compilation and type checking
2. Vite bundles and optimizes frontend
3. Cargo builds optimized Rust binary
4. Tauri packages the application for the target platform

​

Further Reading

• Tauri Documentation
• React Documentation
• Rust Book
• TanStack Router
• Jotai Documentation