Skip to main content

​
Introduction

Obsidian Chess Studio is a comprehensive, open-source chess analysis platform that combines powerful engine integration, advanced game analysis, and intelligent training systems. This guide will help you understand the architecture and get started with development.

​
Technology Stack

Frontend

  • React 19 with TypeScript
  • Vite for fast builds and HMR
  • Mantine UI component library
  • TanStack Router for routing
  • Jotai for state management
  • Zustand for additional stores

Backend

  • Rust for performance
  • Tauri 2 desktop framework
  • Diesel ORM for database
  • SQLite for data storage
  • Tokio async runtime
  • Rayon for parallelization

Chess Logic

  • chessops (TypeScript)
  • shakmaty (Rust)
  • pgn-reader (Rust)
  • vampirc-uci for engine communication
  • Chessground for board UI

Development Tools

  • pnpm package manager
  • Biome for linting/formatting
  • Vitest for testing
  • Cargo for Rust builds
  • GitHub Actions for CI/CD

​
Development Philosophy

Obsidian Chess Studio is built with several core principles:

​
Performance First

  • Rust backend handles computationally intensive operations (database queries, PGN parsing, position analysis)
  • Aggressive optimizations in release builds (opt-level 3, thin LTO)
  • Parallel processing using Rayon for multi-core utilization
  • Efficient caching for frequent queries and position lookups
  • SQLite indexing for sub-second searches across millions of games

​
Cross-Platform Support

Built on Tauri 2, the application runs natively on:
  • Windows (x64, ARM64)
  • macOS (Intel, Apple Silicon)
  • Linux (AppImage, deb, rpm)
  • Android (in progress)

​
User Experience

  • Modern UI with Mantine components
  • Responsive design that adapts to screen sizes
  • Keyboard-first navigation with customizable shortcuts
  • Dark/light themes with full customization
  • i18n support with 17+ languages

​
Open Source Commitment

  • GPL-3.0 license ensuring freedom
  • Transparent development on GitHub
  • Community-driven features and translations
  • No telemetry or tracking

​
Project Structure

Obsidian-Chess-Studio/
├── src/                    # Frontend (React + TypeScript)
│   ├── components/        # Reusable UI components
│   ├── features/          # Feature modules
│   ├── routes/            # TanStack Router pages
│   ├── state/             # Jotai atoms and Zustand stores
│   ├── utils/             # Helper functions
│   └── locales/           # i18n translations
├── src-tauri/             # Backend (Rust + Tauri)
│   ├── src/
│   │   ├── app/          # Platform-specific code
│   │   ├── chess/        # Engine management
│   │   ├── db/           # Database layer
│   │   └── *.rs          # Command modules
│   └── Cargo.toml
├── package.json           # Frontend dependencies
└── vite.config.ts         # Vite configuration
See Project Structure for detailed breakdown.

​
Getting Started

1

Install Prerequisites

2

Clone Repository

git clone [email protected]:luisrivasnoriega/Obsidian-Chess-Studio.git
cd Obsidian-Chess-Studio
3

Install Dependencies

pnpm install
4

Run Development Server

pnpm dev
This starts Vite dev server on port 1420 and launches the Tauri app with hot reload.

​
Development Commands

# Start dev server with hot reload
pnpm dev

# Start Vite only (without Tauri)
pnpm start-vite

​
Architecture Overview

Obsidian Chess Studio uses a frontend-backend split architecture:

​
Frontend Responsibilities

  • UI rendering and user interactions
  • Chess board visualization (Chessground)
  • State management (Jotai/Zustand)
  • Routing and navigation
  • Client-side validation

​
Backend Responsibilities

  • Database operations (SQLite)
  • PGN parsing and game import
  • Chess engine management (UCI protocol)
  • Position search and indexing
  • File system operations
  • External API integrations (Lichess, Chess.com)

​
Communication

Frontend and backend communicate via Tauri commands: 
// Frontend invokes backend command
import { invoke } from '@tauri-apps/api/core';

const games = await invoke('search_position', {
  fen: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
  exact: true
});

// Backend handles command
#[tauri::command]
pub fn search_position(fen: String, exact: bool) -> Result<Vec<Game>> {
    // Database query logic
}
See Architecture for detailed information.

​
Key Features to Explore

Multi-Engine Analysis

Simultaneous analysis with multiple UCI engines. See src-tauri/src/chess/manager.rs

Database Search

Fast position search across millions of games. See src-tauri/src/db/search.rs

Opening Repertoire

Tree-based repertoire training with spaced repetition. See src/features/variants/

Game Analysis

Automatic mistake detection and ACPL calculation. See src-tauri/src/dashboard_games_history.rs

​
Next Steps

Building from Source

Platform-specific build instructions

Contributing

Guidelines for contributing code

Testing

Running and writing tests

Translations

Adding new languages

​
Community

GitHub Discussions

Ask questions and share ideas

Issues

Report bugs and request features

Contributing

Contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us