# neknaj/typingmp architecture

> Architecture diagram of the GitHub repository neknaj/typingmp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neknaj/typingmp
- Repository: https://github.com/neknaj/typingmp

## Overview

##### Project type and purpose
- This is a multi‐platform typing tutor application (“Neknaj Typing MP”) written in Rust.
- It has a single shared core (business logic and state), and four thin platform‐specific “backends”: a desktop GUI, a terminal TUI, a WebAssembly browser build, and a bare‐metal UEFI app.
- The README confirms its goal: demonstrate Rust’s portability by reusing core logic across vastly different environments.

##### File structure
- Top‐level Rust files and config:
- Cargo.toml, Cargo.lock, build.rs → Rust build configuration.
- src/ → all Rust source files.
- .github/workflows/release.yml → CI for release builds.
- Platform backends in src/:
- gui.rs, tui.rs, wasm.rs, uefi.rs → entry points for each target.
- wasm_debug_logger.rs → support for WebSocket debug logging in WASM.
- logger_server.js, package.json, package-lock.json → NodeJS WebSocket server for WASM debug logs.
- Core and shared layers:
- app.rs, typing.rs, model.rs, parser.rs → core logic (“The Brain”).
- ui.rs → UI abstraction producing Renderable lists.
- renderer.rs → rendering engine (gui_renderer vs tui_renderer).
- layout_data.rs → data tables for Japanese Romaji→Kana; timestamp.rs, timestamp.rs, etc.
- Examples, fonts, scripts:
- examples/*.ntq → problem file examples.
- fonts/*.txt → font metric data.
- run_uefi*.ps1, rust_multibackend_app.efi → build/run helpers for UEFI.
- index.html, script.py → static assets for the WASM build and optional Python server.

##### README for architecture insights
- It explicitly defines four layers:
1. Backends (gui.rs, tui.rs, wasm.rs, uefi.rs)
2. Rendering Engine (renderer.rs)
3. UI Abstraction Layer (ui.rs)
4. Core Logic (app.rs, typing.rs, model.rs, parser.rs, etc.)
- It highlights a “body” (backends) vs “brain” (core logic) separation and how feature flags select the active backend at compile time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers vertically: Core at bottom, then UI, Renderer, Backends, External/Assets

    %% Core Logic Layer
    subgraph "Core Logic (The Brain)" 
        direction TB
        App["app.rs"] 
        Typing["typing.rs"]
        Model["model.rs"]
        Parser["parser.rs"]
        Timestamp["timestamp.rs"]
        LayoutData["layout_data.rs"]
    end

    %% UI Abstraction Layer
    subgraph "UI Abstraction Layer"
        direction TB
        UI["ui.rs"]
    end

    %% Rendering Engine Layer
    subgraph "Rendering Engine"
        direction TB
        Renderer["renderer.rs"]
    end

    %% Backends Layer
    subgraph "Backends (Feature-flag Selected)"
        direction TB
        GUI["Desktop GUI\n(gui.rs)"]
        TUI["Terminal TUI\n(tui.rs)"]
        WASM["WebAssembly\n(wasm.rs)"]
        UEFI["UEFI\n(uefi.rs)"]
    end

    %% WASM Debug Support
    subgraph "WASM Debug Logging Support"
        direction TB
        WASMLogger["wasm_debug_logger.rs"]
    end

    %% External Services & Emulators
    subgraph "External Services & Emulators"
        direction TB
        LoggerServer["logger_server.js"]
        PackageJSON["package.json"]
        PackageLock["package-lock.json"]
        PythonServer["script.py"]
        IndexHTML["index.html"]
        QEMU["QEMU/OVMF Emulator"]
    end

    %% Assets & Helpers
    subgraph "Assets & Helpers"
        direction TB
        Examples["examples/*.ntq"]
        Fonts["fonts/*.txt"]
        UEFIGuide["run_uefi.ps1\nrun_uefi_hyperv.ps1\nrust_multibackend_app.efi"]
        BuildConfig["Cargo.toml\nCargo.lock\nbuild.rs\n.github/workflows/release.yml"]
        Entry["main.rs\nlib.rs"]
    end

    %% Data Flows
    GUI -->|User Input| App
    TUI -->|User Input| App
    WASM -->|User Input| App
    UEFI -->|User Input| App

    App -->|State Update| UI
    UI -->|Renderable Items| Renderer
    Renderer -->|Draw Output| GUI
    Renderer -->|Draw Output| TUI
    Renderer -->|Draw Output| WASM
    Renderer -->|Draw Output| UEFI

    %% WASM debug logger flow
    WASM -->|Debug Logs| WASMLogger
    WASMLogger -- Dashed --> LoggerServer
    LoggerServer -->|Sends Logs to Browser| WASM

    %% UEFI emulator flow
    UEFI -- Dashed --> QEMU

    %% Assets flows
    Examples -->|Problem Files| App
    Fonts -->|Font Metrics| Renderer
    BuildConfig -->|Build & CI| Entry
    Entry -->|Library & Entry| App

    %% Static assets for WASM hosting
    IndexHTML -->|Served to Browser| WASM
    PythonServer -->|Serves| IndexHTML

    %% Click Events for component mapping
    click App "https://github.com/neknaj/typingmp/blob/master/src/app.rs"
    click Typing "https://github.com/neknaj/typingmp/blob/master/src/typing.rs"
    click Model "https://github.com/neknaj/typingmp/blob/master/src/model.rs"
    click Parser "https://github.com/neknaj/typingmp/blob/master/src/parser.rs"
    click Timestamp "https://github.com/neknaj/typingmp/blob/master/src/timestamp.rs"
    click LayoutData "https://github.com/neknaj/typingmp/blob/master/src/layout_data.rs"
    click UI "https://github.com/neknaj/typingmp/blob/master/src/ui.rs"
    click Renderer "https://github.com/neknaj/typingmp/blob/master/src/renderer.rs"
    click GUI "https://github.com/neknaj/typingmp/blob/master/src/gui.rs"
    click TUI "https://github.com/neknaj/typingmp/blob/master/src/tui.rs"
    click WASM "https://github.com/neknaj/typingmp/blob/master/src/wasm.rs"
    click WASMLogger "https://github.com/neknaj/typingmp/blob/master/src/wasm_debug_logger.rs"
    click UEFI "https://github.com/neknaj/typingmp/blob/master/src/uefi.rs"
    click LoggerServer "https://github.com/neknaj/typingmp/blob/master/logger_server.js"
    click PackageJSON "https://github.com/neknaj/typingmp/blob/master/package.json"
    click PackageLock "https://github.com/neknaj/typingmp/blob/master/package-lock.json"
    click IndexHTML "https://github.com/neknaj/typingmp/blob/master/index.html"
    click PythonServer "https://github.com/neknaj/typingmp/blob/master/script.py"
    click Examples "https://github.com/neknaj/typingmp/tree/master/examples/"
    click Fonts "https://github.com/neknaj/typingmp/tree/master/fonts/"
    click UEFIGuide "https://github.com/neknaj/typingmp/blob/master/run_uefi.ps1"
    click BuildConfig "https://github.com/neknaj/typingmp/blob/master/Cargo.toml"
    click Entry "https://github.com/neknaj/typingmp/blob/master/src/main.rs"

    %% Styling
    classDef core fill:#D0E4F5,stroke:#3B7BBF
    classDef ui fill:#DFF5D0,stroke:#4F8F28
    classDef renderer fill:#DFF5D0,stroke:#4F8F28
    classDef backend fill:#F5D0D0,stroke:#BF3B3B
    classDef external fill:#E0E0E0,stroke:#888888
    classDef assets fill:#F5E0D0,stroke:#BF8F3B

    class App,Typing,Model,Parser,Timestamp,LayoutData core
    class UI ui
    class Renderer renderer
    class GUI,TUI,WASM,UEFI backend
    class WASMLogger,LoggerServer,PackageJSON,PackageLock,PythonServer,IndexHTML,QEMU external
    class Examples,Fonts,UEFIGuide,BuildConfig,Entry assets
```
