# quangngonz/cs50x_live_display_leaderboard architecture

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

- Interactive diagram: https://gitdiagram.com/quangngonz/cs50x_live_display_leaderboard
- Repository: https://github.com/quangngonz/cs50x_live_display_leaderboard

## Overview

##### Main Components
- Frontend Application: Label a “Client” or “UI” component representing the React app. Note that it’s comprised of several subcomponents (Leaderboard, Recent Submissions, Header, TeamCard, Title, Counter, AddHintForm, and DecryptedText) and uses Material-UI for styling and react libraries like react-query for state management.
- Custom Hooks and Services: Include a component representing custom hooks (useFetchQuestions, useRecentSubmission, useTeamRankings) and another for services (Supabase client in src/services/supabaseClient.js) that handle data fetching and subscriptions.
- External Services:
- Supabase: This is the backend (a managed PostgreSQL database) that provides real-time data updates. It connects to the application via the configured Supabase client. Make sure to note that it uses appropriate RLS policies to secure tables.
- API Endpoints: An external API (e.g., the one in the hints and scoring logic) is referenced in the hook files and components, so include an “API Server” element that interacts with the database.

##### Relationships and Interactions
- For example, from the Leaderboard and RecentSubmissions React components → (consume) custom hooks (useTeamRankings, useRecentSubmission) → (subscribe/poll) Supabase.
- Similarly, illustrate the Admin Panel’s AddHintForm sending hint data through its custom hook → to the Supabase backend.
- External API calls (as triggered by hooks and components for actions like scoring) that might be managed separately.
- One-way data flow from Supabase (real-time database updates) back to the UI components via subscriptions, which then trigger UI updates (possibly through React Query’s cache invalidation).

##### Architectural Patterns and Design Principles
- Component-Based UI: The frontend follows a modular design using React components placed in the src/components/ directory.
- Separation of Concerns: Different directories group functionality (components, hooks, pages, services). The admin functionality is clearly segmented from the leaderboard display.
- Real-time Updates: Highlight the real-time subscription mechanism using Supabase. Emphasize that the custom hooks encapsulate the subscription logic for live updates.
- External Configuration and Deployment: Note the inclusion of Vite and Vercel configuration files, which influence how the application is built and deployed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        App["React App"]:::frontend
        subgraph "Pages"
            LBPage["Leaderboard Page"]:::frontend
            AdminPage["Admin Page"]:::frontend
            AdminLoginPage["AdminLogin Page"]:::frontend
        end
        subgraph "Components"
            LeaderboardComp["Leaderboard Component"]:::frontend
            RecentSubmissionsComp["Recent Submissions Component"]:::frontend
            HeaderComp["Header Component"]:::frontend
            TeamCardComp["TeamCard Component"]:::frontend
            TitleComp["Title Component"]:::frontend
            CounterComp["Counter Component"]:::frontend
            AddHintFormComp["AddHintForm Component"]:::frontend
            DecryptedTextComp["DecryptedText Component"]:::frontend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        useFetchQuestions["useFetchQuestions"]:::data
        useRecentSubmission["useRecentSubmission"]:::data
        useTeamRankings["useTeamRankings"]:::data
        SupabaseService["Supabase Service"]:::data
    end

    %% External Services
    subgraph "External Services"
        SupabaseDB["Supabase Database (PostgreSQL, real-time)"]:::external
        APIServer["API Server"]:::external
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        ViteBuild["Vite Build Config"]:::deployment
        VercelDeployment["Vercel Deployment"]:::deployment
    end

    %% Connections - Frontend Routing
    App -->|"routes"| LBPage
    App -->|"routes"| AdminPage
    App -->|"routes"| AdminLoginPage

    %% Page to Components Rendering
    LBPage -->|"renders"| LeaderboardComp
    LBPage -->|"renders"| RecentSubmissionsComp
    LBPage -->|"renders"| TitleComp
    LBPage -->|"renders"| CounterComp

    AdminPage -->|"renders"| AddHintFormComp
    AdminPage -->|"renders"| HeaderComp
    AdminPage -->|"renders"| TeamCardComp
    AdminPage -->|"renders"| DecryptedTextComp

    %% Components using Custom Hooks
    LeaderboardComp -->|"uses"| useTeamRankings
    RecentSubmissionsComp -->|"uses"| useRecentSubmission
    AddHintFormComp -->|"uses"| useFetchQuestions

    %% Custom Hooks interacting with Supabase Service
    useTeamRankings -->|"subscribes"| SupabaseService
    useRecentSubmission -->|"subscribes"| SupabaseService
    useFetchQuestions -->|"fetches"| SupabaseService

    %% Supabase Service Real-Time Updates
    SupabaseService -->|"real-time updates"| SupabaseDB

    %% External API Call
    useTeamRankings -->|"calls"| APIServer

    %% Deployment Flow
    ViteBuild -->|"builds"| App
    VercelDeployment -->|"hosts"| App

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef data fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef deployment fill:#d1c4e9,stroke:#5e35b1,stroke-width:2px;

    %% Click Events
    click App "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/App.jsx"
    click LeaderboardComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/Leaderboard/Leaderboard.jsx"
    click RecentSubmissionsComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/RecentSubmissions/RecentSubmissions.jsx"
    click HeaderComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/Header/Header.jsx"
    click TeamCardComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/TeamCard/TeamCard.jsx"
    click TitleComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/Title/Title.jsx"
    click CounterComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/Counter/Counter.jsx"
    click AddHintFormComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/AddHintForm/AddHintForm.jsx"
    click DecryptedTextComp "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/components/DecryptedText/DecryptedText.jsx"
    click LBPage "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/pages/Leaderboard/LeaderboardPage.jsx"
    click AdminPage "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/pages/Admin/AdminPage.jsx"
    click AdminLoginPage "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/pages/AdminLogin/AdminLogin.jsx"
    click useFetchQuestions "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/hooks/useFetchQuestions.js"
    click useRecentSubmission "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/hooks/useRecentSubmission.js"
    click useTeamRankings "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/hooks/useTeamRankings.js"
    click SupabaseService "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/src/services/supabaseClient.js"
    click VercelDeployment "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/vercel.json"
    click ViteBuild "https://github.com/quangngonz/cs50x_live_display_leaderboard/blob/main/vite.config.js"
```
