lanspread/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

LanSpread2 is a peer-to-peer (P2P) game distribution system with a Tauri desktop application frontend. It enables users to share games over local networks using mDNS discovery and QUIC protocol for peer communication.

Common Development Commands

Build

# Development (opens UI, needs user interaction)
cargo tauri dev

# Debug build for very quick testing (without bundle)
cargo tauri build --debug --no-bundle

# Relase build for testing (without bundling)
cargo tauri build --no-bundle

# Production (with bundling)
cargo tauri build -- --profile release-lto

Build Profiles

• release: Default release profile with debug info, assertions enabled, overflow checks on, for testing
• release-lto: Optimized for distribution with LTO enabled, debug symbols stripped, smaller binary, only for production

Code Quality

# Lint all code
cargo clippy

# Format code (nightly Rust)
cargo +nightly fmt

Testing

# Run all tests
cargo test --workspace

# Run tests for a specific crate
cargo test -p lanspread-peer

# Run a specific test
cargo test -p lanspread-peer test_name

# Run tests with output
cargo test -- --nocapture

Dependencies

# Update frontend dependencies (Deno)
deno outdated --update --latest

Architecture

LanSpread follows a layered, modular architecture with clear separation of concerns:

Crate Structure

The project is organized as a Cargo workspace with 7 crates:

Foundation Layer:

• lanspread-utils: Utility macros and helpers used across all crates
• lanspread-db: Core data structures (Game, GameFileDescription, game metadata)

Protocol & Communication:

• lanspread-proto: P2P communication protocol definitions
  • Message types: Request (Ping, ListGames, GetGame, etc.), Response, Message trait
  • Serialization: JSON with serde

Network Discovery & Compatibility:

• lanspread-mdns: mDNS service discovery and advertisement

  • Advertises and discovers "_lanspread._udp.local." services on LAN
  • Uses mdns-sd crate

• lanspread-compat: Compatibility layer for legacy ETI game database format

  • Reads legacy game.db SQLite databases
  • Converts EtiGame structs to modern Game struct

Core P2P Engine:

• lanspread-peer: (~97KB) Central orchestration for all P2P functionality
  • QUIC-based networking with length-delimited frame codec (tokio-util)
  • Manages peer-to-peer connections and game synchronization
  • Handles file streaming with chunk transfers and path validation
  • Communicates via unbounded channels (PeerEvent, PeerCommand)
  • Implements retry logic for requesting games from peers
  • Entry point: start_peer() function

Application Layer:

• lanspread-tauri-deno-ts: Tauri desktop application
  • Binary + Library crate for the UI layer
  • IPC commands: request_games, install_game, etc.
  • Manages LanSpreadState for peer controller, game DB, and downloads
  • Uses Tauri plugins: logging, shell, dialogs, persistent storage
  • Allocates MiMalloc for memory efficiency

Data Flow

User (Tauri UI)
    ↓ IPC Commands (request_games, install_game)
    ↓
lanspread-tauri-deno-ts (app layer)
    ↓
lanspread-peer (P2P engine)
    ├─ lanspread-mdns (discovers peers via mDNS)
    ├─ lanspread-proto (constructs P2P messages)
    ├─ lanspread-compat (reads legacy game databases)
    └─ QUIC Network ↔ Other Peers
    ↓
lanspread-db (game data structures)
    ↓
Result → Back to UI

Key Architectural Details

1. Async/Await: Tokio runtime throughout for non-blocking I/O
2. Message Passing: Unbounded channels for inter-component communication (events and commands)
3. Protocol: Length-delimited QUIC frames with JSON serialization
4. Service Discovery: Automatic mDNS announcement and discovery of peers
5. File Streaming: Chunked transfer with path validation for security
6. Legacy Support: Backwards compatibility with ETI game database format
7. Error Handling: Custom error types via eyre crate

Development Practices

From AGENTS.md

• Always check code with cargo clippy and fix any issues
• Always format with cargo +nightly fmt after completing changes
• Use appropriate Rust log levels when debugging:
  • RUST_LOG=lanspread=debug for module-specific debugging
  • RUST_LOG=info,lanspread=debug for general info + module debug

Performance Considerations

• Use release-lto profile for final builds to enable Link-Time Optimization
• MiMalloc is used for the Tauri app to reduce memory overhead
• QUIC protocol chosen for efficient P2P communication
• Length-delimited framing reduces message parsing overhead

Important Implementation Notes

Logging

The codebase uses tracing and log crates. Note: There's documented uncertainty about their exact relationship (see LESSONS_LEARNED.md). The client app uses log crate; be consistent with whichever is used in the component you're modifying.

Legacy Database Support

Some users may have old ETI format game databases. The lanspread-compat crate handles reading these. When querying games, both modern and legacy formats are considered.

Path Validation

File transfers validate paths to prevent directory traversal attacks. All file operations use validated paths from lanspread-peer.

Retry Logic

lanspread-peer includes retry logic for requesting games from peers. This handles transient network failures in P2P discovery.

Known Design Decisions

Why not Tauri + Leptos? Leptos adds unnecessary complexity. Tauri is designed to transfer backend Rust to frontend JavaScript world, but with Leptos the frontend becomes Rust, creating a double translation. The current Tauri + Deno/TypeScript approach is cleaner.

Why Tauri? Simple setup, easy development with cargo tauri dev, easy testing and bundling with installers, small final binary (~13MB).

File Organization

crates/
├── lanspread-db/          # Core data models
├── lanspread-utils/       # Macros & utilities
├── lanspread-proto/       # Protocol definitions
├── lanspread-compat/      # Legacy ETI compatibility
├── lanspread-mdns/        # mDNS discovery
├── lanspread-peer/        # P2P engine (largest, most complex)
└── lanspread-tauri-deno-ts/
    ├── src-tauri/         # Rust Tauri backend
    └── (sibling dirs)     # Deno/TypeScript frontend code

Additional Resources

• README.md: Build and development prerequisites
• LESSONS_LEARNED.md: Architectural decisions and trade-offs
• AGENTS.md: Code quality guidelines
• TODO.md: Tracked work items