# jackpham1510/hfcyt architecture

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

- Interactive diagram: https://gitdiagram.com/jackpham1510/hfcyt
- Repository: https://github.com/jackpham1510/hfcyt

## Overview

##### Project type and purpose
- This is a full-stack, real-time web application called “How Fast Can You Type?”
- The backend is built with Node.js and Express and uses Socket.io for real-time bidirectional communication.
- The frontend is a React single-page app (SPA) using Element-UI for styling.

##### File structure
- Top-level
- index.js – server entry point
- lib.js – shared business-logic/functions (e.g., typing-speed calculations, room management)
- package.json/.gitignore – project metadata and excludes
- client/
- package.json – React app metadata
- public/ – static assets (index.html, manifest.json)
- src/ – React components (App.js, Intro.js, service worker, CSS, tests)
- No database directory or config, so state is likely in memory or ephemeral.

##### Key insights from README
- Run the Node/Express server (index.js) in the root, then run the React dev server in client/
- In production, Express can be configured to serve the React build output from client/build
- Stack: Express (HTTP), Socket.io (WebSockets), React (UI), Element-UI (styles)

##### Main components
a. Client Layer
- Browser running React SPA
- UI components (App, Intro) styled with Element-UI
- Socket.io client library (in registerServiceWorker or App.js)
b. Server Layer
- Node.js + Express HTTP server (index.js)
- Socket.io server module attached to Express
- lib.js: game logic, typing-speed computation, room/user management
c. Data/State
- In-memory game state (no external DB)
d. External Services
- Deployment host (e.g., Heroku)
- Optional CDN for serving static assets

##### Relationships and interactions
- React UI emits “key-press” events over WebSocket → Socket.io server
- Server processes events (via lib.js) → calculates WPM, accuracy
- Server broadcasts state updates (“score-update”, “leaderboard”) to all connected clients
- HTTP (Express) serves SPA assets (in production) and/or health-check endpoints
- Browser may fall back to REST endpoints for initial page load

##### Architectural patterns and design principles
- Separation of concerns:
- UI rendering and state management in React
- Real-time messaging and game logic on the server
- Event-driven architecture with WebSockets
- Single code branch for shared logic in lib.js (if reused on client in future)

##### Technologies and frameworks to annotate
- React.js, Element-UI
- Node.js, Express.js
- Socket.io (client + server)
- (Heroku) or another PaaS—optional

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        ReactApp["React SPA"]:::frontend
        AppComp["App Component"]:::frontend
        IntroComp["Intro Component"]:::frontend
        StylesIndex["Global Stylesheet: index.css"]:::frontend
        StylesApp["Global Stylesheet: App.css"]:::frontend
        EntryPoint["React Entry Point"]:::frontend
        RegisterSW["Service Worker Registration"]:::frontend
        StaticIndexHTML["Static Asset: index.html"]:::frontend
        StaticManifest["Static Asset: manifest.json"]:::frontend
        ClientPackage["client/package.json"]:::frontend
        ClientGitIgnore["client/.gitignore"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        ExpressServer["Express HTTP Server\n(index.js)"]:::backend
        SocketServer["Socket.io Server"]:::backend
        LibLogic["Shared Game Logic (lib.js)"]:::logic
        RootPackage["package.json"]:::backend
        RootGitIgnore[".gitignore"]:::backend
    end

    %% External Services
    subgraph "External Services"
        DeploymentHost["Deployment Host (Heroku)"]:::external
        CDN["CDN for Static Assets"]:::external
    end

    %% Relationships
    ReactApp -->|"WebSocket: typing event"| SocketServer
    SocketServer -->|"WebSocket: score update"| ReactApp
    ReactApp -->|"HTTP GET / (prod)"| ExpressServer
    ExpressServer -->|"serves index.html"| StaticIndexHTML
    ExpressServer -->|"serves manifest.json"| StaticManifest
    SocketServer -->|uses| LibLogic
    ExpressServer -->|uses| LibLogic
    DeploymentHost -->|hosts| ExpressServer
    CDN -->|delivers| StaticIndexHTML
    CDN -->|delivers| StaticManifest

    %% Click Events
    click ReactApp "https://github.com/jackpham1510/hfcyt/tree/master/client/"
    click AppComp "https://github.com/jackpham1510/hfcyt/blob/master/client/src/App.js"
    click IntroComp "https://github.com/jackpham1510/hfcyt/blob/master/client/src/Intro.js"
    click StylesIndex "https://github.com/jackpham1510/hfcyt/blob/master/client/src/index.css"
    click StylesApp "https://github.com/jackpham1510/hfcyt/blob/master/client/src/App.css"
    click EntryPoint "https://github.com/jackpham1510/hfcyt/blob/master/client/src/index.js"
    click RegisterSW "https://github.com/jackpham1510/hfcyt/blob/master/client/src/registerServiceWorker.js"
    click StaticIndexHTML "https://github.com/jackpham1510/hfcyt/blob/master/client/public/index.html"
    click StaticManifest "https://github.com/jackpham1510/hfcyt/blob/master/client/public/manifest.json"
    click ClientPackage "https://github.com/jackpham1510/hfcyt/blob/master/client/package.json"
    click ClientGitIgnore "https://github.com/jackpham1510/hfcyt/blob/master/client/.gitignore"
    click ExpressServer "https://github.com/jackpham1510/hfcyt/blob/master/index.js"
    click LibLogic "https://github.com/jackpham1510/hfcyt/blob/master/lib.js"
    click RootPackage "https://github.com/jackpham1510/hfcyt/blob/master/package.json"
    click RootGitIgnore "https://github.com/jackpham1510/hfcyt/blob/master/.gitignore"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px;
    classDef logic fill:#c9f,stroke:#333,stroke-width:1px;
    classDef external fill:#eee,stroke:#333,stroke-width:1px;
```
