# shahidshabbir-se/race-engineer architecture

> Architecture diagram of the GitHub repository shahidshabbir-se/race-engineer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shahidshabbir-se/race-engineer
- Repository: https://github.com/shahidshabbir-se/race-engineer

## Overview

##### Project Type and Purpose
- This is a desktop, full-stack application (“Race Engineer Application”) built with Tauri (Rust) as the backend and SvelteKit (TypeScript + Skeleton UI) as the frontend.
- Purpose: Read Richard Burns Rally (RBR) JSON files directly from the user’s RBR installation directory and display game state data (cars, tracks) in a user-friendly GUI. No database—pure file I/O.

##### File Structure
- Top-level directories:
- app/ – Contains the Tauri + SvelteKit application
- data/ – Sample RBR JSON files & extraction scripts for development/testing
- docs/ – Requirements, data models, AI-coding guidelines
- In app/:
- src-tauri/ – Rust backend (“core”)
– core/*.rs – Modules handling domain logic (cars, stages, settings)
– main.rs – Tauri setup, IPC handlers
– tauri.conf.json, build.rs
- src/ – SvelteKit frontend
– routes/ – Page layouts, navigation (dashboard, platform, settings)
– components/ – UI pieces (carData, carGroups, spinner, etc.)
- config files: package.json, pnpm-lock.yaml, vite.config.js, tsconfig.json, svelte.config.js
- Testing: Emphasis on unit tests for both Rust and Svelte components (per README).

##### Key Architecture Insights from README
- All business logic + file access in Rust backend via Tauri.
- Frontend is “thin”—handles only presentation & user events.
- Persistent configuration limited to one setting: RBR install path (stored in Tauri settings).

a. Main Components
- Frontend (SvelteKit + Skeleton UI)
- Backend (Tauri + Rust core modules)
- Local File System (RBR JSON files, user’s config)
- Development Data Source (data/ samples)
b. Relationships & Interactions
1. User interacts with Frontend UI
2. Frontend sends IPC requests (via Tauri’s JavaScript-Rust bridge)
3. Tauri backend receives requests → invokes Rust core modules
4. Rust modules read RBR JSON files from the file system
5. Parse data into in-memory domain models → return results over IPC
6. Frontend renders data in components
c. Architectural Patterns & Principles
- Clear separation of concerns: UI vs. business logic
- IPC-based interface boundary (Tauri)
- Domain-driven design in Rust modules (car.rs, stages_data.rs, settings.rs)
- No database layer; direct file access
- Sample data directory for test harnesses—separate from production FS
d. Key Technologies & Frameworks
- SvelteKit (routes, components) + Skeleton UI
- Tauri (Rust + webview), ts-rs for TypeScript bindings
- Vite (dev server, build)
- Node.js / pnpm for frontend dependencies
- Shell script (extract_json_samples.sh) for populating sample data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend UI Layer"
        direction TB
        UI["SvelteKit UI"]:::frontend
        Routes["SvelteKit Routes"]:::frontend
        Components["UI Components"]:::frontend
    end

    %% IPC Layer
    subgraph "IPC Layer (Tauri Bridge)"
        direction TB
        IPCMain["Tauri IPC Bridge<br/>(main.rs)"]:::ipc
        IPCLib["Tauri Rust Library Wrapper<br/>(lib.rs)"]:::ipc
    end

    %% Backend Core Services
    subgraph "Backend Layer (Rust Core Services)"
        direction TB
        CarService["CarService<br/>(car.rs)"]:::backend
        CarDataService["CarDataService<br/>(car_data.rs)"]:::backend
        CarGroupsService["CarGroupsService<br/>(car_groups.rs)"]:::backend
        CarGroupMapService["CarGroupMapService<br/>(car_group_map.rs)"]:::backend
        CarModelsService["CarModelsService<br/>(car_models.rs)"]:::backend
        PersonalCarService["RallySimFansPersonalCarService<br/>(rallysimfans_personal_car.rs)"]:::backend
        PersonalStageService["RallySimFansPersonalStageService<br/>(rallysimfans_personal_stage.rs)"]:::backend
        SettingsService["SettingsService<br/>(settings.rs)"]:::backend
        StagesDataService["StagesDataService<br/>(stages_data.rs)"]:::backend
        TauriConfig["Tauri Config<br/>(tauri.conf.json & Cargo.toml)"]:::backend
    end

    %% External File Systems and Data
    subgraph "External File Systems & Dev Data"
        direction TB
        ProdFS["RBR JSON Files<br/>(User's Install Dir)"]:::fs
        SampleScript["Extract Sample Data Script<br/>(extract_json_samples.sh)"]:::fs
        SampleFiles1["Dev Sample JSONs<br/>(data/rbr.samples)"]:::fs
        SampleFiles2["Dev Sample JSONs<br/>(data/data/rbr.samples)"]:::fs
        DocsReq["Requirements Doc<br/>(docs/requirements.md)"]:::fs
        DocsDataModel["Data Model Doc<br/>(docs/data-model-rbr.md)"]:::fs
    end

    %% Connections
    UI -->|"user events / view"| IPCMain
    Routes --> IPCMain
    Components --> IPCMain

    IPCMain -->|"invoke handlers"| IPCLib
    IPCLib -->|"calls getCarData() / getStageData() / getSettings() etc."| CarService
    IPCLib --> CarDataService
    IPCLib --> CarGroupsService
    IPCLib --> CarGroupMapService
    IPCLib --> CarModelsService
    IPCLib --> PersonalCarService
    IPCLib --> PersonalStageService
    IPCLib --> SettingsService
    IPCLib --> StagesDataService
    IPCLib --> TauriConfig

    CarService -->|"read JSON"| ProdFS
    CarDataService --> ProdFS
    CarGroupsService --> ProdFS
    CarGroupMapService --> ProdFS
    CarModelsService --> ProdFS
    PersonalCarService --> ProdFS
    PersonalStageService --> ProdFS
    StagesDataService --> ProdFS
    SettingsService --> ProdFS

    SampleScript --> SampleFiles1
    SampleScript --> SampleFiles2
    SampleFiles1 --> CarService
    SampleFiles2 --> CarService

    DocsReq --- CarService
    DocsDataModel --- CarService

    %% Legend
    subgraph Legend
        direction TB
        FC["Blue = Frontend"]:::frontend
        IC["Orange = IPC Layer"]:::ipc
        BC["Green = Backend"]:::backend
        FS["Gray = External FS & Docs"]:::fs
    end

    %% Click events
    click UI "https://github.com/shahidshabbir-se/race-engineer/tree/main/app/src/"
    click Routes "https://github.com/shahidshabbir-se/race-engineer/tree/main/app/src/routes/"
    click Components "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src/components/*.svelte"
    click IPCMain "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/main.rs"
    click IPCLib "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/lib.rs"
    click CarService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/car.rs"
    click CarDataService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/car_data.rs"
    click CarGroupsService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/car_groups.rs"
    click CarGroupMapService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/car_group_map.rs"
    click CarModelsService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/car_models.rs"
    click PersonalCarService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/rallysimfans_personal_car.rs"
    click PersonalStageService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/rallysimfans_personal_stage.rs"
    click SettingsService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/settings.rs"
    click StagesDataService "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/src/core/stages_data.rs"
    click TauriConfig "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/tauri.conf.json"
    click TauriConfig "https://github.com/shahidshabbir-se/race-engineer/blob/main/app/src-tauri/Cargo.toml"
    click SampleScript "https://github.com/shahidshabbir-se/race-engineer/blob/main/data/extract_json_samples.sh"
    click SampleFiles1 "https://github.com/shahidshabbir-se/race-engineer/blob/main/data/rbr.samples/*.json"
    click SampleFiles2 "https://github.com/shahidshabbir-se/race-engineer/blob/main/data/data/rbr.samples/*.json"
    click DocsReq "https://github.com/shahidshabbir-se/race-engineer/blob/main/docs/requirements.md"
    click DocsDataModel "https://github.com/shahidshabbir-se/race-engineer/blob/main/docs/data-model-rbr.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#2a7fdb,color:#000;
    classDef ipc fill:#ffe0b2,stroke:#f57c00,color:#000;
    classDef backend fill:#dcedc8,stroke:#558b2f,color:#000;
    classDef fs fill:#eeeeee,stroke:#757575,color:#000;
```
