# graysonhuey/leaderboards architecture

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

- Interactive diagram: https://gitdiagram.com/graysonhuey/leaderboards
- Repository: https://github.com/graysonhuey/leaderboards

## Overview

##### Project type and purpose
- From the file tree and README (“WARU Band Olympics Leaderboards!”), we see a React-based, TypeScript single-page application (SPA) whose goal is to display and manage leaderboards for a band competition.
- It has no custom backend code; instead it relies on Firebase (auth + data) as a backend‐as‐a‐service and on Netlify for CI/CD and hosting.

##### High-level architectural components
a. Developers & CI/CD
- Source code in GitHub repo (.github/workflows/deploy.yml)
- On each push: GitHub Actions → runs build → pushes to Netlify
b. Hosting & CDN
- Netlify reads netlify.toml → deploys Vite build output → serves static assets via global CDN
c. Client application
- Browser loads index.html → main.tsx → renders React App
- Uses Tailwind CSS for styling (tailwind.config.js, postcss.config.js)
- Vite for dev/build (vite.config.ts)
d. Frontend modules
- src/App.tsx – root component & router
- src/contexts/AuthContext.tsx – provides user state & protected routes
- src/components – pages & UI pieces (Login, Dashboard, AdminPanel, Leaderboard, SectionSelector, Layout)
- src/lib/firebase.ts – config + instances for Firebase Auth & Firestore
e. External services
- Firebase Authentication – user login/role management
- Firebase Firestore (or Realtime DB) – stores leaderboard data

##### Data flow & interactions
- User opens browser → DNS → CDN → index.html + JS bundle
- React App mounts → AuthContext checks Firebase Auth state
→ if unauthenticated → redirects to LoginPage → signs in via Firebase Auth
→ if authenticated → fetches leaderboard data from Firestore via firebase.ts
→ client renders Dashboard or AdminPanel; AdminPanel writes updates to Firestore
- All reads/writes go over HTTPS REST/WebSocket to Firebase endpoints

##### Key architectural patterns
- SPA with client-side routing & protected routes (ProtectedRoute component)
- Context API for global auth state
- Component composition for layouts & pages
- BaaS (Firebase) decouples backend concerns—no custom server code
- CI/CD pipeline with GitHub Actions → Netlify

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Developer Workflow"
    Repo["GitHub Repo"]:::cicd
    GH["GitHub Actions build & deploy"]:::cicd
  end

  subgraph "Hosting & CDN"
    NETLIFY["Netlify (Build & Deploy)"]:::hosting
    CDN["Global CDN"]:::hosting
  end

  subgraph "Client (Browser)"
    BROWSER["Browser"]:::client
    HTML["index.html"]:::client
    MAIN["src/main.tsx"]:::client
    APP["src/App.tsx"]:::client
    AUTHCTX["src/contexts/AuthContext.tsx"]:::client
    PROT["src/components/ProtectedRoute.tsx"]:::client
    LOGIN["src/components/LoginPage.tsx"]:::client
    DASH["src/components/Dashboard.tsx"]:::client
    ADMIN["src/components/AdminPanel.tsx"]:::client
    SECTION["src/components/SectionLeaderboard.tsx"]:::client
    SELECTOR["src/components/SectionSelector.tsx"]:::client
    LAYOUT["src/components/Layout.tsx"]:::client
    FIRE["src/lib/firebase.ts"]:::client
    TYPES["src/types/index.ts"]:::client
    VITECFG["vite.config.ts"]:::client
    POSTCSS["postcss.config.js"]:::client
    TAILWIND["tailwind.config.js"]:::client
  end

  subgraph "Firebase Services"
    AUTH["Firebase Authentication"]:::service
    DB["Firebase Firestore"]:::service
  end

  Repo -->|"push code"|GH
  GH -->|"runs build & deploy"|NETLIFY
  NETLIFY -->|"serves static assets"|CDN
  CDN -->|"HTTPS GET"|BROWSER

  BROWSER -->|"loads"|HTML
  HTML -->|"bootstraps"|MAIN
  MAIN -->|"renders"|APP
  APP -->|"uses AuthContext"|AUTHCTX
  AUTHCTX -->|"auth state"|AUTH
  APP -->|"routes via ProtectedRoute"|PROT
  PROT -->|"/login if unauthenticated"|LOGIN
  PROT -->|"protected routes"|DASH
  PROT -->|"protected routes"|ADMIN
  DASH -->|"read data"|DB
  ADMIN -->|"write data"|DB
  APP -->|"layout composes"|LAYOUT
  LAYOUT -->|"renders"|SECTION
  LAYOUT -->|"renders"|SELECTOR

  click GH "https://github.com/graysonhuey/leaderboards/blob/main/.github/workflows/deploy.yml"
  click NETLIFY "https://github.com/graysonhuey/leaderboards/blob/main/netlify.toml"
  click HTML "https://github.com/graysonhuey/leaderboards/blob/main/index.html"
  click VITECFG "https://github.com/graysonhuey/leaderboards/blob/main/vite.config.ts"
  click POSTCSS "https://github.com/graysonhuey/leaderboards/blob/main/postcss.config.js"
  click TAILWIND "https://github.com/graysonhuey/leaderboards/blob/main/tailwind.config.js"
  click MAIN "https://github.com/graysonhuey/leaderboards/blob/main/src/main.tsx"
  click APP "https://github.com/graysonhuey/leaderboards/blob/main/src/App.tsx"
  click AUTHCTX "https://github.com/graysonhuey/leaderboards/blob/main/src/contexts/AuthContext.tsx"
  click FIRE "https://github.com/graysonhuey/leaderboards/blob/main/src/lib/firebase.ts"
  click PROT "https://github.com/graysonhuey/leaderboards/blob/main/src/components/ProtectedRoute.tsx"
  click LOGIN "https://github.com/graysonhuey/leaderboards/blob/main/src/components/LoginPage.tsx"
  click DASH "https://github.com/graysonhuey/leaderboards/blob/main/src/components/Dashboard.tsx"
  click ADMIN "https://github.com/graysonhuey/leaderboards/blob/main/src/components/AdminPanel.tsx"
  click SECTION "https://github.com/graysonhuey/leaderboards/blob/main/src/components/SectionLeaderboard.tsx"
  click SELECTOR "https://github.com/graysonhuey/leaderboards/blob/main/src/components/SectionSelector.tsx"
  click LAYOUT "https://github.com/graysonhuey/leaderboards/blob/main/src/components/Layout.tsx"
  click TYPES "https://github.com/graysonhuey/leaderboards/blob/main/src/types/index.ts"

  classDef cicd fill:#f9f,stroke:#333,stroke-width:1px
  classDef hosting fill:#ff9,stroke:#333,stroke-width:1px
  classDef client fill:#9f9,stroke:#333,stroke-width:1px
  classDef service fill:#9cf,stroke:#333,stroke-width:1px
```
