Skip to content
Dice Chess Lab

System Architecture

Monorepo Overview

Section titled “Monorepo Overview”

The Dice Chess Lab project follows a monorepo structure, housing both backend and frontend applications seamlessly in one repository along with our scripts and data files.

  • backend-api/: The server-side API responsible for game generation, database persistence, state management, and interaction with external dependencies.
  • frontend-pwa/: The user interface and Progressive Web Application implementation. It proxies API requests to the backend during local development and is served statically by the backend in production mode.
  • docs/: The centralized Astro Starlight knowledge base you are reading now.

Tech Stack

Section titled “Tech Stack”

Our technology choices have been deeply influenced by performance needs and developer velocity expectations.

Backend

Section titled “Backend”
  • Framework: FastAPI (Python 3.12+)
  • Database: SQLite (Async using aiosqlite with WAL mode enabled)
  • ORM: SQLAlchemy

Frontend

Section titled “Frontend”
  • Framework: Svelte 5
  • Tooling: Vite
  • Styling: TailwindCSS

See also: Frontend Architecture for store patterns, API integration, and testing conventions.

Hardware Constraints

Section titled “Hardware Constraints”

Our infrastructure consists of two environments:

  • Production: Raspberry Pi 4 (4GB RAM)
  • Staging: Raspberry Pi 3 (1GB RAM)

We design and optimize for the lowest common denominator (Staging). Because the application must run smoothly on the 1GB Pi 3 to pass staging validation, certain design decisions must be strictly adhered to:

Release and Deployment Flow

Section titled “Release and Deployment Flow”
  • Releases are created manually via workflow dispatch (Ops: Release).
  • Production deploy runs from CD: Production Deploy after successful release workflow completion.
  • The release tag is resolved into Docker build arg APP_VERSION during CI image builds.
  • The frontend build exports this as VITE_APP_VERSION, so the running PWA can show the deployed version in the UI.

See also: Release Rollback Guide for bad-tag recovery and Infrastructure Migration Guide for host-level rollback planning.

Backend Implications

Section titled “Backend Implications”
  • Memory usage must be minimized at all costs. We prefer streaming results over large bulk fetching, avoiding heavy data processing in memory.
  • Using SQLite in WAL (Write-Ahead Logging) mode reduces SD card wear and improves concurrency over raw SQLite mode.
  • We do not use hefty dependencies like Pandas or heavy ML toolkits if an external service or a custom lightweight algorithm can suffice.

See also: SQLite Performance for runtime PRAGMA tuning and verification details.

Frontend Implications

Section titled “Frontend Implications”
  • No Heavy Client-Side Filtering: If we implement paginated views or game browsing, all filtering, sorting, and pagination must be done via backend API endpoints. Attempting to ship massive arrays to the Svelte application and sorting them client-side will instantly crash browsers running on mid-to-lower tier devices or max out the hardware resources on the Pi sending the payload.
  • All SVG or image rasterization happens with lightweight tools (e.g., cairosvg rather than loading headless Chrome instances).

Admin Dashboard and User Management

Section titled “Admin Dashboard and User Management”

The application features a secure, tabbed Admin Dashboard for platform maintenance and user lifecycle management.

User Management

Section titled “User Management”
  • Approval Workflow: The platform is gated for a closed beta. Admins can approve pending users.
  • Role Assignment: Admins can promote other users to the ADMIN role.
  • Access Control: Users can be blocked/unblocked by toggling their is_active status. Blocked users lose access to the platform.
  • Safety: Admins are prevented from accidentally demoting or blocking their own accounts.

System Maintenance

Section titled “System Maintenance”
  • Game Synchronization: Triggers fetching and storing games from the external Dice Chess API in batches.
  • Move History Sync: Enriches stored games with full move history necessary for the Trainer mode, running with configurable delays to respect external rate limits. Additionally, when a user attempts to open a game that is currently missing its history, an on-demand synchronization is triggered automatically.

See Move Synchronization Lifecycle for the full end-to-end flow, including the metadata list, the missing-history backfill, and the timeout behavior.

The raw player-history metadata itself is documented in Player History API, while the detailed step-by-step payload lives in Game Move History API.