# nimarion/timing-stream-overlay architecture

> Architecture diagram of the GitHub repository nimarion/timing-stream-overlay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nimarion/timing-stream-overlay
- Repository: https://github.com/nimarion/timing-stream-overlay

## Overview

##### Project type and purpose
- This is a front-end single-page application (SPA) built with React, TypeScript and Vite, designed to run as a browser-source overlay in streaming software (e.g., OBS).
- Its purpose is to display live event data—timing and wind speeds, race results, start lists, reaction times and upcoming events—by fetching from an external timing API or data service and rendering it in different on-screen “pages.”

##### File structure
- Top level: configuration files (.eslintrc.cjs, tsconfig.json, tailwind.config.js, vite.config.ts), index.html and package.json.
- src/: application code
- src/pages/: route-level components (reactions.tsx, results.tsx, etc.)
- src/components/: reusable UI components (CountryFlag, ResultsTable, WindIcon, etc.)
- src/router.ts: SPA routing setup
- src/utilts.ts and src/country-utils.ts: data-transformation helpers
- src/country-mapping.json: static lookup data
- src/main.tsx and src/index.css: React entry point and global styles

##### README for additional insights
- Features: lists the various overlay “pages” and shows screenshot examples.
- No internal service code: the app relies on an external data source (likely a REST or WebSocket timing API).
- Deployment: intended for live streaming events (hosted on a CDN, loaded into OBS).

##### Focus points
- Be granular: break out each page (Live Time, Results, Startlist, etc.) if the engineer needs that detail.
- Data-flow direction and refresh intervals (polling or websockets).
- That there is no backend in the repo: data is fully external.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Configuration
    subgraph "Build & Deployment" 
        direction TB
        packageJson["package.json"]:::infra
        tailwindConfig["tailwind.config.js"]:::infra
        postcssConfig["postcss.config.js"]:::infra
        tsconfig["tsconfig.json"]:::infra
        tsconfigNode["tsconfig.node.json"]:::infra
        eslintConfig[".eslintrc.cjs"]:::infra
        viteEnv["src/vite-env.d.ts"]:::infra
        viteConfig["vite.config.ts"]:::infra
    end

    %% Static CDN / Public Host
    subgraph "Static CDN / Public Host"
        direction TB
        publicDir["public/"]:::infra
        indexHtml["index.html"]:::infra
    end

    %% React SPA Overlay
    subgraph "React SPA (Overlay)" 
        direction TB
        mainTSX["src/main.tsx"]:::frontend
        indexCSS["src/index.css"]:::frontend
        router["src/router.ts"]:::frontend
        appWrapper["_app.tsx"]:::frontend

        subgraph "Pages"
            direction TB
            timing["Live Timing Page"]:::frontend
            reactions["Reactions Page"]:::frontend
            results["Results Page"]:::frontend
            startlist["Startlist Page"]:::frontend
            upcoming["Upcoming Events Page"]:::frontend
        end

        subgraph "Reusable UI Components"
            direction TB
            countryFlag["Country Flag"]:::component
            windIcon["Wind Icon"]:::component
            reactionsTable["Reactions Table"]:::component
            resultsTable["Results Table"]:::component
            startlistTable["Startlist Table"]:::component
            upcomingTable["Upcoming Events Table"]:::component
        end

        subgraph "Data Transformation Helpers"
            direction TB
            utilts["General Utilities"]:::helper
            countryUtils["Country Lookup Logic"]:::helper
            countryMap["Country Data Mapping"]:::data
        end
    end

    %% External Services
    TimingAPI("External Timing API / Data Service"):::external
    OBS("OBS Browser Source"):::external

    %% Connections
    packageJson --> viteConfig
    viteConfig --> indexHtml
    indexHtml --> publicDir
    publicDir --> mainTSX
    mainTSX --> indexCSS
    mainTSX --> router
    router --> appWrapper
    appWrapper --> timing
    appWrapper --> reactions
    appWrapper --> results
    appWrapper --> startlist
    appWrapper --> upcoming

    timing --> countryFlag
    timing --> windIcon
    timing --> reactionsTable
    results --> resultsTable
    startlist --> startlistTable
    upcoming --> upcomingTable

    countryFlag --> countryUtils
    windIcon --> utilts
    reactionsTable --> utilts
    resultsTable --> utilts
    startlistTable --> utilts
    upcomingTable --> utilts
    countryUtils --> countryMap

    mainTSX <--> TimingAPI
    mainTSX --> OBS

    %% Click Events
    click mainTSX "https://github.com/nimarion/timing-stream-overlay/blob/main/src/main.tsx"
    click indexCSS "https://github.com/nimarion/timing-stream-overlay/blob/main/src/index.css"
    click viteConfig "https://github.com/nimarion/timing-stream-overlay/blob/main/vite.config.ts"
    click indexHtml "https://github.com/nimarion/timing-stream-overlay/blob/main/index.html"
    click router "https://github.com/nimarion/timing-stream-overlay/blob/main/src/router.ts"
    click appWrapper "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/_app.tsx"
    click timing "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/timing.tsx"
    click reactions "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/reactions.tsx"
    click results "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/results.tsx"
    click startlist "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/startlist.tsx"
    click upcoming "https://github.com/nimarion/timing-stream-overlay/blob/main/src/pages/upcoming.tsx"
    click countryFlag "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/CountryFlag.tsx"
    click windIcon "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/WindIcon.tsx"
    click reactionsTable "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/ReactionsTable.tsx"
    click resultsTable "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/ResultsTable.tsx"
    click startlistTable "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/StartlistTable.tsx"
    click upcomingTable "https://github.com/nimarion/timing-stream-overlay/blob/main/src/components/UpcomingTable.tsx"
    click utilts "https://github.com/nimarion/timing-stream-overlay/blob/main/src/utilts.ts"
    click countryUtils "https://github.com/nimarion/timing-stream-overlay/blob/main/src/country-utils.ts"
    click countryMap "https://github.com/nimarion/timing-stream-overlay/blob/main/src/country-mapping.json"
    click publicDir "https://github.com/nimarion/timing-stream-overlay/tree/main/public/"
    click packageJson "https://github.com/nimarion/timing-stream-overlay/blob/main/package.json"
    click tailwindConfig "https://github.com/nimarion/timing-stream-overlay/blob/main/tailwind.config.js"
    click postcssConfig "https://github.com/nimarion/timing-stream-overlay/blob/main/postcss.config.js"
    click tsconfig "https://github.com/nimarion/timing-stream-overlay/blob/main/tsconfig.json"
    click tsconfigNode "https://github.com/nimarion/timing-stream-overlay/blob/main/tsconfig.node.json"
    click eslintConfig "https://github.com/nimarion/timing-stream-overlay/blob/main/.eslintrc.cjs"
    click viteEnv "https://github.com/nimarion/timing-stream-overlay/blob/main/src/vite-env.d.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef infra fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef component fill:#FFF5B1,stroke:#D4A72C,color:#735C0F
    classDef helper fill:#FFE7D9,stroke:#E5534B,color:#B31D28
    classDef data fill:#F0F0F0,stroke:#CCCCCC,color:#333333
    classDef external fill:#F3E5F5,stroke:#893AA1,color:#631A86
```
