# marco-vanin/betterhit architecture

> Architecture diagram of the GitHub repository marco-vanin/betterhit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marco-vanin/betterhit
- Repository: https://github.com/marco-vanin/betterhit

## Overview

BetterHit is a mobile-first web app for scanning Hitster QR codes and identifying songs. Its main workflow loads a local song database, scans a QR code, parses its URL, looks up the song, and displays the result with optional details and a short YouTube preview. The graph follows the sampled app and component calls; the README documents scanning and identification, while the song database path is confirmed by the hook. Other unsampled wiring is omitted.

Main entry points: [`src/App.tsx`](https://github.com/marco-vanin/betterhit/blob/main/src/App.tsx) (App state and orchestration), [`src/hooks/useSongsDatabase.ts`](https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useSongsDatabase.ts) (Song database lookup), [`src/hooks/useQRScanner.ts`](https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useQRScanner.ts) (QR scanner lifecycle), [`src/components/MusicPlayer.tsx`](https://github.com/marco-vanin/betterhit/blob/main/src/components/MusicPlayer.tsx) (Music player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App flow"]
  node_entry["React entry<br/>[main.tsx]"]
  node_app["App state and orchestration<br/>[App.tsx]"]
  node_welcome["Welcome screen<br/>[Welcome.tsx]"]
  node_errors["Error display<br/>[ErrorDisplay.tsx]"]
end

subgraph group_scan["QR scanning"]
  node_scanner_ui["Scanner view<br/>[Scanner.tsx]"]
  node_scanner_hook["QR scanner lifecycle<br/>[useQRScanner.ts]"]
end

subgraph group_songs["Song lookup"]
  node_hitster["QR URL parser<br/>[hitster.ts]"]
  node_db_hook["Song database lookup"]
  node_song_file["French song database<br/>[summer-party.json]"]
  node_constants["App configuration<br/>[constants.ts]"]
  node_scan_logic["Scan logic hook<br/>[useScanLogic.ts]"]
end

subgraph group_playback["Results and playback"]
  node_result["Song result view<br/>[Result.tsx]"]
  node_music["Music player<br/>[MusicPlayer.tsx]"]
  node_youtube_util["YouTube URL parser<br/>[youtube.ts]"]
end

node_user(("User"))
node_camera["Device camera"]
node_youtube["YouTube player service"]

node_user -->|"opens app"| node_entry
node_entry -->|"renders"| node_app
node_app -->|"loads lookup"| node_db_hook
node_db_hook -->|"reads path"| node_constants
node_db_hook -->|"fetches data"| node_song_file
node_app -->|"starts scanner"| node_scanner_hook
node_scanner_hook -->|"requests access"| node_camera
node_scanner_hook -->|"calls scan callback"| node_app
node_app -->|"parses scanned URL"| node_hitster
node_app -->|"looks up song"| node_db_hook
node_app -->|"renders welcome"| node_welcome
node_welcome -->|"renders errors"| node_errors
node_app -->|"renders scanner"| node_scanner_ui
node_app -->|"renders result"| node_result
node_result -->|"renders player"| node_music
node_music -->|"extracts video ID"| node_youtube_util
node_music -->|"loads player API"| node_youtube
node_scan_logic -->|"uses lookup"| node_db_hook
node_scan_logic -->|"parses URL"| node_hitster

click node_entry "https://github.com/marco-vanin/betterhit/blob/main/src/main.tsx"
click node_app "https://github.com/marco-vanin/betterhit/blob/main/src/App.tsx"
click node_welcome "https://github.com/marco-vanin/betterhit/blob/main/src/components/Welcome.tsx"
click node_errors "https://github.com/marco-vanin/betterhit/blob/main/src/components/ErrorDisplay.tsx"
click node_scanner_ui "https://github.com/marco-vanin/betterhit/blob/main/src/components/Scanner.tsx"
click node_scanner_hook "https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useQRScanner.ts"
click node_hitster "https://github.com/marco-vanin/betterhit/blob/main/src/utils/hitster.ts"
click node_db_hook "https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useSongsDatabase.ts"
click node_song_file "https://github.com/marco-vanin/betterhit/blob/main/public/songs/french/summer-party.json"
click node_constants "https://github.com/marco-vanin/betterhit/blob/main/src/config/constants.ts"
click node_scan_logic "https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useScanLogic.ts"
click node_result "https://github.com/marco-vanin/betterhit/blob/main/src/components/Result.tsx"
click node_music "https://github.com/marco-vanin/betterhit/blob/main/src/components/MusicPlayer.tsx"
click node_youtube_util "https://github.com/marco-vanin/betterhit/blob/main/src/utils/youtube.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_entry,node_app,node_welcome,node_errors,node_user toneBlue
class node_scanner_ui,node_scanner_hook toneAmber
class node_hitster,node_db_hook,node_song_file,node_constants,node_scan_logic toneMint
class node_result,node_music,node_youtube_util toneRose
class node_camera,node_youtube toneIndigo
```

## Components

### App flow

- [React entry](https://github.com/marco-vanin/betterhit/blob/main/src/main.tsx): `src/main.tsx`
- [App state and orchestration](https://github.com/marco-vanin/betterhit/blob/main/src/App.tsx): `src/App.tsx`
- [Welcome screen](https://github.com/marco-vanin/betterhit/blob/main/src/components/Welcome.tsx): `src/components/Welcome.tsx`
- [Error display](https://github.com/marco-vanin/betterhit/blob/main/src/components/ErrorDisplay.tsx): `src/components/ErrorDisplay.tsx`

### QR scanning

- [Scanner view](https://github.com/marco-vanin/betterhit/blob/main/src/components/Scanner.tsx): `src/components/Scanner.tsx`
- [QR scanner lifecycle](https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useQRScanner.ts): `src/hooks/useQRScanner.ts`

### Song lookup

- [QR URL parser](https://github.com/marco-vanin/betterhit/blob/main/src/utils/hitster.ts): `src/utils/hitster.ts`
- [Song database lookup](https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useSongsDatabase.ts): `src/hooks/useSongsDatabase.ts`
- [French song database](https://github.com/marco-vanin/betterhit/blob/main/public/songs/french/summer-party.json): `public/songs/french/summer-party.json`
- [App configuration](https://github.com/marco-vanin/betterhit/blob/main/src/config/constants.ts): `src/config/constants.ts`
- [Scan logic hook](https://github.com/marco-vanin/betterhit/blob/main/src/hooks/useScanLogic.ts): `src/hooks/useScanLogic.ts`

### Results and playback

- [Song result view](https://github.com/marco-vanin/betterhit/blob/main/src/components/Result.tsx): `src/components/Result.tsx`
- [Music player](https://github.com/marco-vanin/betterhit/blob/main/src/components/MusicPlayer.tsx): `src/components/MusicPlayer.tsx`
- [YouTube URL parser](https://github.com/marco-vanin/betterhit/blob/main/src/utils/youtube.ts): `src/utils/youtube.ts`

### Other components

- **User**
- **Device camera**
- **YouTube player service**

## Connections

- User → React entry: opens app (evidence: `src/main.tsx`)
- React entry → App state and orchestration: renders (evidence: `src/main.tsx`)
- App state and orchestration → Song database lookup: loads lookup (evidence: `src/App.tsx`)
- Song database lookup → App configuration: reads path (evidence: `src/hooks/useSongsDatabase.ts`)
- Song database lookup → French song database: fetches data (evidence: `src/hooks/useSongsDatabase.ts`)
- App state and orchestration → QR scanner lifecycle: starts scanner (evidence: `src/App.tsx`)
- QR scanner lifecycle → Device camera: requests access (evidence: `src/hooks/useQRScanner.ts`)
- QR scanner lifecycle → App state and orchestration: calls scan callback (evidence: `src/hooks/useQRScanner.ts`)
- App state and orchestration → QR URL parser: parses scanned URL (evidence: `src/App.tsx`)
- App state and orchestration → Song database lookup: looks up song (evidence: `src/App.tsx`)
- App state and orchestration → Welcome screen: renders welcome (evidence: `src/App.tsx`)
- Welcome screen → Error display: renders errors (evidence: `src/components/Welcome.tsx`)
- App state and orchestration → Scanner view: renders scanner (evidence: `src/App.tsx`)
- App state and orchestration → Song result view: renders result (evidence: `src/App.tsx`)
- Song result view → Music player: renders player (evidence: `src/components/Result.tsx`)
- Music player → YouTube URL parser: extracts video ID (evidence: `src/components/MusicPlayer.tsx`)
- Music player → YouTube player service: loads player API (evidence: `src/components/MusicPlayer.tsx`)
- Scan logic hook → Song database lookup: uses lookup (evidence: `src/hooks/useScanLogic.ts`)
- Scan logic hook → QR URL parser: parses URL (evidence: `src/hooks/useScanLogic.ts`)
