# yasirawan4831/keyboard-tester architecture

> Architecture diagram of the GitHub repository yasirawan4831/keyboard-tester, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yasirawan4831/keyboard-tester
- Repository: https://github.com/yasirawan4831/keyboard-tester

## Overview

Keyboard Tester combines browser-side physical-key diagnostics, a timed typing test, and locally persisted performance history. The main workflow runs from the user’s key presses or typed input through the relevant test logic to live feedback and results; the Statistics page reads saved results. Separate API routes provide health, result-payload validation, and a local-only leaderboard response. The README documents broader UI capabilities, but unsampled component wiring is shown only where supported by the tree and documentation.

Main entry points: [`components/typing/TypingTest.tsx`](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/typing/TypingTest.tsx) (Typing test UI), [`components/keyboard/KeyboardTester.tsx`](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/KeyboardTester.tsx) (Keyboard tester), [`hooks/useKeyboard.ts`](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useKeyboard.ts) (Keyboard session), [`hooks/useTypingTest.ts`](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useTypingTest.ts) (Typing session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_keyboard["Keyboard diagnostics"]
  node_home["Home page<br/>[page.tsx]"]
  node_keyboard_tester["Keyboard tester<br/>[KeyboardTester.tsx]"]
  node_keyboard_hook["Keyboard session<br/>[useKeyboard.ts]"]
  node_keyboard_logic["Key diagnostics<br/>[keyboard.ts]"]
  node_keyboard_layout["Keyboard layout<br/>[KeyboardLayout.ts]"]
  node_keyboard_view["Virtual keyboard<br/>[Keyboard.tsx]"]
  node_diagnostics_view["Diagnostics panel<br/>[Diagnostics.tsx]"]
end

subgraph group_typing["Typing and results"]
  node_typing_page["Typing test page<br/>[page.tsx]"]
  node_typing_view["Typing test UI<br/>[TypingTest.tsx]"]
  node_typing_hook["Typing session<br/>[useTypingTest.ts]"]
  node_timer["Countdown timer<br/>[useTimer.ts]"]
  node_typing_logic["Typing calculations<br/>[typing.ts]"]
  node_result_view["Test results<br/>[TypingResults.tsx]"]
end

subgraph group_stats["History and statistics"]
  node_history_hook["History access<br/>[useLocalStorage.ts]"]
  node_history_store[("Local history<br/>[storage.ts]")]
  node_stats_page["Statistics page<br/>[page.tsx]"]
  node_stats_views["Stats views"]
end

subgraph group_api["API routes"]
  node_health_route["Health endpoint<br/>[route.ts]"]
  node_results_route["Results endpoint<br/>[route.ts]"]
  node_validation["Payload validation<br/>[validation.ts]"]
  node_leaderboard_route["Leaderboard endpoint<br/>[route.ts]"]
end

node_visitor(("Visitor"))
node_hardware(("Physical keyboard"))
node_api_caller(("API consumer"))

node_visitor -->|"opens"| node_home
node_home -->|"renders"| node_keyboard_tester
node_hardware -->|"key events"| node_keyboard_hook
node_keyboard_tester -->|"uses session"| node_keyboard_hook
node_keyboard_hook -->|"loads layout"| node_keyboard_layout
node_keyboard_hook -->|"updates state"| node_keyboard_logic
node_keyboard_tester -->|"renders"| node_keyboard_view
node_keyboard_tester -->|"renders"| node_diagnostics_view
node_visitor -->|"opens"| node_typing_page
node_typing_page -->|"renders"| node_typing_view
node_visitor -->|"types input"| node_typing_view
node_typing_view -->|"uses session"| node_typing_hook
node_typing_hook -->|"controls timer"| node_timer
node_typing_hook -->|"calculates results"| node_typing_logic
node_typing_view -->|"shows results"| node_result_view
node_typing_view -->|"records result"| node_history_hook
node_history_hook -->|"reads and writes"| node_history_store
node_visitor -->|"opens"| node_stats_page
node_stats_page -->|"loads history"| node_history_hook
node_stats_page -->|"renders"| node_stats_views
node_api_caller -->|"requests health"| node_health_route
node_api_caller -->|"submits result"| node_results_route
node_results_route -->|"validates payload"| node_validation
node_api_caller -->|"requests leaderboard"| node_leaderboard_route

click node_home "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/page.tsx"
click node_keyboard_tester "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/KeyboardTester.tsx"
click node_keyboard_hook "https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useKeyboard.ts"
click node_keyboard_logic "https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/keyboard.ts"
click node_keyboard_layout "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/KeyboardLayout.ts"
click node_keyboard_view "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/Keyboard.tsx"
click node_diagnostics_view "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/Diagnostics.tsx"
click node_typing_page "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/typing-test/page.tsx"
click node_typing_view "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/typing/TypingTest.tsx"
click node_typing_hook "https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useTypingTest.ts"
click node_timer "https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useTimer.ts"
click node_typing_logic "https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/typing.ts"
click node_result_view "https://github.com/yasirawan4831/keyboard-tester/blob/main/components/typing/TypingResults.tsx"
click node_history_hook "https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useLocalStorage.ts"
click node_history_store "https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/storage.ts"
click node_stats_page "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/stats/page.tsx"
click node_stats_views "https://github.com/yasirawan4831/keyboard-tester/tree/main/components/stats"
click node_health_route "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/health/route.ts"
click node_results_route "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/results/route.ts"
click node_validation "https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/validation.ts"
click node_leaderboard_route "https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/leaderboard/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_keyboard_tester,node_keyboard_hook,node_keyboard_logic,node_keyboard_layout,node_keyboard_view,node_diagnostics_view toneBlue
class node_typing_page,node_typing_view,node_typing_hook,node_timer,node_typing_logic,node_result_view toneAmber
class node_history_hook,node_history_store,node_stats_page,node_stats_views,node_api_caller toneMint
class node_health_route,node_results_route,node_validation,node_leaderboard_route toneRose
class node_visitor,node_hardware toneIndigo
```

## Components

### Keyboard diagnostics

- [Home page](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/page.tsx): `app/page.tsx`
- [Keyboard tester](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/KeyboardTester.tsx): `components/keyboard/KeyboardTester.tsx`
- [Keyboard session](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useKeyboard.ts): `hooks/useKeyboard.ts`
- [Key diagnostics](https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/keyboard.ts): `lib/keyboard.ts`
- [Keyboard layout](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/KeyboardLayout.ts): `components/keyboard/KeyboardLayout.ts`
- [Virtual keyboard](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/Keyboard.tsx): `components/keyboard/Keyboard.tsx`
- [Diagnostics panel](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/keyboard/Diagnostics.tsx): `components/keyboard/Diagnostics.tsx`

### Typing and results

- [Typing test page](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/typing-test/page.tsx): `app/typing-test/page.tsx`
- [Typing test UI](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/typing/TypingTest.tsx): `components/typing/TypingTest.tsx`
- [Typing session](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useTypingTest.ts): `hooks/useTypingTest.ts`
- [Countdown timer](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useTimer.ts): `hooks/useTimer.ts`
- [Typing calculations](https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/typing.ts): `lib/typing.ts`
- [Test results](https://github.com/yasirawan4831/keyboard-tester/blob/main/components/typing/TypingResults.tsx): `components/typing/TypingResults.tsx`

### History and statistics

- [History access](https://github.com/yasirawan4831/keyboard-tester/blob/main/hooks/useLocalStorage.ts): `hooks/useLocalStorage.ts`
- [Local history](https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/storage.ts): `lib/storage.ts`
- [Statistics page](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/stats/page.tsx): `app/stats/page.tsx`
- [Stats views](https://github.com/yasirawan4831/keyboard-tester/tree/main/components/stats): `components/stats`

### API routes

- [Health endpoint](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/health/route.ts): `app/api/health/route.ts`
- [Results endpoint](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/results/route.ts): `app/api/results/route.ts`
- [Payload validation](https://github.com/yasirawan4831/keyboard-tester/blob/main/lib/validation.ts): `lib/validation.ts`
- [Leaderboard endpoint](https://github.com/yasirawan4831/keyboard-tester/blob/main/app/api/leaderboard/route.ts): `app/api/leaderboard/route.ts`

### Other components

- **Visitor**
- **Physical keyboard**
- **API consumer**

## Connections

- Visitor → Home page: opens
- Home page → Keyboard tester: renders
- Physical keyboard → Keyboard session: key events
- Keyboard tester → Keyboard session: uses session
- Keyboard session → Keyboard layout: loads layout
- Keyboard session → Key diagnostics: updates state
- Keyboard tester → Virtual keyboard: renders
- Keyboard tester → Diagnostics panel: renders
- Visitor → Typing test page: opens
- Typing test page → Typing test UI: renders
- Visitor → Typing test UI: types input
- Typing test UI → Typing session: uses session
- Typing session → Countdown timer: controls timer
- Typing session → Typing calculations: calculates results
- Typing test UI → Test results: shows results
- Typing test UI → History access: records result
- History access → Local history: reads and writes
- Visitor → Statistics page: opens
- Statistics page → History access: loads history
- Statistics page → Stats views: renders
- API consumer → Health endpoint: requests health
- API consumer → Results endpoint: submits result
- Results endpoint → Payload validation: validates payload
- API consumer → Leaderboard endpoint: requests leaderboard