Technical Documentation

Deep dive into Pawn Appétit's architecture, APIs, development setup, and deployment processes. For developers and advanced users.

Application Architecture

Pawn Appétit uses a modern hybrid architecture combining web technologies with native performance.

Frontend (React/TypeScript)

Modern web-based user interface built with React, TypeScript, and Vite

Technologies:

React 18TypeScriptTanStack RouterMantine UIJotai (State Management)

Responsibilities:

User interface rendering and interaction
State management and data flow
Real-time updates and notifications
Theme system and customization

Location: src/ directory

Backend (Rust/Tauri)

High-performance native backend powered by Rust and the Tauri framework

Technologies:

RustTauri v2Tokio (Async Runtime)SQLiteUCI Protocol

Responsibilities:

File system operations and PGN parsing
Chess engine communication (UCI)
Database management and queries
System integration and performance

Location: src-tauri/ directory

Chess Engine Interface

UCI (Universal Chess Interface) communication layer

Technologies:

vampirc-uciTokio Process ManagementMulti-engine Support

Responsibilities:

Engine process lifecycle management
UCI command parsing and execution
Analysis result processing
Engine configuration and options

Location: src-tauri/src/engine/

Database Layer

Game storage and retrieval system with indexing

Technologies:

SQLiteCustom IndexingFTS (Full-Text Search)Position Hashing

Responsibilities:

Game storage in normalized format
Position-based search and filtering
Player and tournament data management
Performance optimization with indexes

Location: src-tauri/src/db/

Data Flow & Communication

How data flows through the application from user interaction to result display.

User Interaction

User performs action in the React frontend

Click, keyboard input, or menu selection
Event handlers capture user intent
State updates triggered via Jotai atoms

Tauri Command

Frontend calls Rust backend via Tauri commands

Type-safe API calls using generated bindings
Async communication with error handling
Serialization/deserialization of data

Business Logic

Rust backend processes the request

File I/O, database queries, or engine communication
Error handling and validation
Data transformation and processing

Response & Update

Results sent back to frontend for display

JSON serialization of results
Frontend state updates
UI re-rendering with new data

Development Setup

Complete guide to setting up your development environment for contributing to Pawn Appétit.

Prerequisites

Node.js 18+ and pnpm package manager
Rust toolchain (latest stable)
Tauri CLI and prerequisites for your platform
Git for version control

Quick Start

Clone: git clone https://github.com/Pawn-Appetit/pawn-appetit.git
Install dependencies: pnpm install
Start development: pnpm tauri dev
Build for production: pnpm tauri build

Development Tools

ESLint and Prettier for code formatting
TypeScript for type safety
Vitest for frontend testing
Rust analyzer for backend development

Debugging

Browser DevTools for frontend debugging
Rust logs via tauri-plugin-log
VSCode debugging configuration included
Performance profiling with Chrome DevTools

Development Commands

Development Mode

pnpm tauri dev

Hot reload for both frontend and backend

Build Production

pnpm tauri build

Optimized build with installers

Run Tests

pnpm test

Frontend and backend test suites

Code Format

pnpm format

Format code with Prettier and Rustfmt

API Reference

Core Tauri commands that bridge the frontend and backend functionality.

File Operations

PGN file parsing, import/export, and file system management

read_games(path: string) → Game[]

write_game(path: string, game: Game) → Result

convert_pgn(input: string, format: string) → string

get_file_metadata(path: string) → FileMetadata

Engine Management

Chess engine communication and analysis

get_best_moves(position: string, options: EngineOptions) → BestMoves

analyze_game(game: Game, depth: number) → Analysis

get_engine_config(path: string) → EngineConfig

stop_engine(engine_id: string) → Result

Database Operations

Game storage, search, and retrieval

create_database(path: string, name: string) → Database

search_position(fen: string, db: string) → PositionStats

get_games(db: string, filter: GameFilter) → Game[]

delete_duplicated_games(db: string) → number

System Integration

Platform-specific features and system information

memory_size() → number

is_bmi2_compatible() → boolean

open_external_link(url: string) → Result

get_platform_info() → PlatformInfo

Type Generation

Pawn Appétit uses TypeScript bindings automatically generated from Rust code using Specta and Tauri Specta.

Generated files: src/bindings/generated.ts contains all type definitions and command signatures. This ensures type safety between frontend and backend.

Build Process

Understanding how Pawn Appétit is built from source code to distributable packages.

Frontend Build

Vite builds the React application

Build Steps:

TypeScript compilation and type checking
Asset optimization and bundling
CSS processing with Tailwind
Code splitting and tree shaking

Output:

dist/ directory with optimized web assets

Rust Compilation

Cargo builds the Tauri backend

Build Steps:

Rust source compilation with optimizations
Dependency resolution and linking
Target platform binary generation
Resource embedding and signing

Output:

Native executable for target platform

Package Creation

Platform-specific installers are generated

Build Steps:

Binary and assets packaging
Installer creation (.msi, .dmg, .deb, .AppImage)
Code signing and notarization (if configured)
Metadata and version information embedding

Output:

Ready-to-distribute installation packages

Deployment Options

Multiple deployment strategies for different use cases and environments.

GitHub Releases

Automated releases via GitHub Actions

Features:

Cross-platform builds for Windows, macOS, Linux
Automatic version detection and changelog
Asset upload and release creation
Download statistics and update checking

Configuration:

Configured in .github/workflows/release.yml

Local Build

Manual building for development and testing

Features:

Quick builds for testing
Debug symbols for troubleshooting
Custom build configurations
Platform-specific optimizations

Configuration:

Use pnpm tauri build for production builds

Docker Build

Containerized building for consistency

Features:

Reproducible build environment
Cross-compilation support
CI/CD integration
Dependency isolation

Configuration:

Dockerfile provided in repository root

Ready to Contribute?

Join our development community and help make Pawn Appétit even better.

Contributing Guide View on GitHub