# davanso/usf-score architecture

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

- Interactive diagram: https://gitdiagram.com/davanso/usf-score
- Repository: https://github.com/davanso/usf-score

## Overview

##### Project type and purpose
- This is a React single-page application (SPA) built with TypeScript and Vite.
- Its goal is to display live soccer match data and player highlights by querying the API-FOOTBALL service, with optional Firebase-backed user login.
- There is no custom backend server—external services (API-FOOTBALL, Firebase) are consumed directly from the client.

##### File structure
- Top-level “public” and “index.html” serve as the SPA entry point.
- “src/” contains:
- “components/” – React UI components (cards, lists, header, highlights).
- “hooks/” – custom hooks for authentication (useLogin) and data fetching.
- “services/” – modules that wrap API calls:
– apiFootball.ts (fetches soccer data)
– backend/firebase.ts (initializes Firebase Auth, Firestore, etc.)
- “lib/utils.ts” – shared helper functions.
- “assets/” – images or static assets.
- “mocks/” – mock data for offline or development.
- Configuration & build files: tsconfig.*, vite.config.ts, eslint.config.js.

##### README for additional insights
- The API-FOOTBALL package version is 3.9.3.
- Auth or state persistence is delegated to Firebase.

##### Main components
a. Client browser / user
b. React SPA layers
- Presentation Layer:
– UI Components (Header, Live_Match_List, Live_Match_Card, Match_Highlight, Best_Players, Main_Competitions)
- State & Hook Layer:
– Custom Hooks (useLogin, potential fetch hooks)
- Service Layer:
– API-Football Service module
– Firebase Service module
- Utility Layer:
– Shared utils.ts
- Mocks:
– Optional mock data endpoints
c. External services
- API-FOOTBALL (third-party REST API)
- Firebase (Auth, Firestore)
d. Local assets & build configuration
- index.html, public/ (static hosting)
- Vite (dev server, build tool)

##### Relationships & data flows
- User interacts with UI components in the browser.
- Components invoke hooks to retrieve or post data.
- Hooks call service layer functions.
- Service layer functions issue HTTP requests to API-FOOTBALL or Firebase.
- Responses propagate back up: Service → Hook → Component → Render.
- Utility functions (lib/utils) support transformation or formatting at any layer.
- Mocks intercept or replace real services during development.

##### Architectural patterns & principles
- Component-based architecture (React).
- Separation of concerns: UI vs. data-fetching hooks vs. API wrappers vs. utils.
- Single responsibility: each service module handles only one external API.
- Unidirectional data flow: top-down props + bottom-up events/hooks.
- Environment-agnostic mocking layer to decouple external dependencies.

##### Key details to capture
- Entry point: index.html → main.tsx → App.tsx.
- Component hierarchy: Header → Live_Match_List → Live_Match_Card.
- Service initializations: Firebase config at startup; API key config in apiFootball.ts.
- Mock vs. production toggles (e.g., when mocks/liveBrazilianMatchMock.ts is used).
- Build configuration (vite.config.ts) for asset handling and environment variables.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Context
    subgraph "Deployment & Entry Point"
        direction TB
        HTML["index.html"]:::deployment
        MainTS["main.tsx"]:::deployment
        HTML --> MainTS
        click HTML "https://github.com/davanso/usf-score/blob/master/index.html"
        click MainTS "https://github.com/davanso/usf-score/blob/master/src/main.tsx"
    end

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Header["Header"]:::ui
        LiveList["Live_Match_List"]:::ui
        LiveCard["Live_Match_Card"]:::ui
        Highlight["Match_Highlight"]:::ui
        BestPlayers["Best_Players"]:::ui
        MainComps["Main_Competitions"]:::ui
        App["App"]:::ui
        HTML --> App
        App --> Header
        Header --> LiveList
        LiveList --> LiveCard
        LiveCard --> Highlight
        Highlight --> BestPlayers
        BestPlayers --> MainComps

        click Header "https://github.com/davanso/usf-score/blob/master/src/components/Header.tsx"
        click LiveList "https://github.com/davanso/usf-score/blob/master/src/components/Live_Match_List.tsx"
        click LiveCard "https://github.com/davanso/usf-score/blob/master/src/components/Live_Match_Card.tsx"
        click Highlight "https://github.com/davanso/usf-score/blob/master/src/components/Match_Highlight.tsx"
        click BestPlayers "https://github.com/davanso/usf-score/blob/master/src/components/Best_Players.tsx"
        click MainComps "https://github.com/davanso/usf-score/blob/master/src/components/Main_Competitions.tsx"
        click App "https://github.com/davanso/usf-score/blob/master/src/App.tsx"
    end

    %% Hooks & State Layer
    subgraph "Hooks & State Layer"
        direction TB
        UseLogin["useLogin"]:::hooks
        FetchHook["useFetchData"]:::hooks
        App --> UseLogin
        App --> FetchHook

        click UseLogin "https://github.com/davanso/usf-score/blob/master/src/hooks/useLogin.ts"
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        APIFootball["API-Football Service"]:::service
        FirebaseSvc["Firebase Service"]:::service
        FetchHook --> APIFootball
        UseLogin --> FirebaseSvc

        click APIFootball "https://github.com/davanso/usf-score/blob/master/services/apiFootball.ts"
        click FirebaseSvc "https://github.com/davanso/usf-score/blob/master/src/backend/firebase.ts"
    end

    %% Utilities
    subgraph "Utility Layer"
        direction TB
        Utils["utils.ts"]:::utils
        FetchHook --- Utils
        APIFootball --- Utils
        UseLogin --- Utils

        click Utils "https://github.com/davanso/usf-score/blob/master/src/lib/utils.ts"
    end

    %% Mock Layer
    subgraph "Mock Data (Dev Only)" 
        direction TB
        OddsMock["OddsMock"]:::mock
        LiveBrazilMock["liveBrazilianMatchMock"]:::mock
        FetchHook -.-> OddsMock
        FetchHook -.-> LiveBrazilMock

        click OddsMock "https://github.com/davanso/usf-score/blob/master/mocks/OddsMock.ts"
        click LiveBrazilMock "https://github.com/davanso/usf-score/blob/master/mocks/liveBrazilianMatchMock.ts"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ExtAPIFootball["API-FOOTBALL REST API"]:::external
        ExtFirebase["Firebase (Auth, Firestore)"]:::external
        APIFootball -->|"GET live matches"| ExtAPIFootball
        FirebaseSvc -->|"POST login / GET user"| ExtFirebase
    end

    %% Build Tool
    subgraph "Build & Config"
        direction TB
        Vite["vite.config.ts"]:::config
        MainTS --> Vite
        click Vite "https://github.com/davanso/usf-score/blob/master/vite.config.ts"
    end

    %% Styles and Legend
    classDef ui fill:#D0E8FF,stroke:#0288D1,stroke-width:2px;
    classDef hooks fill:#E8F5E9,stroke:#43A047,stroke-width:2px;
    classDef service fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px;
    classDef utils fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px;
    classDef mock fill:#ECEFF1,stroke:#607D8B,stroke-dasharray: 5 5;
    classDef external fill:#FFEBEE,stroke:#E53935,stroke-width:2px;
    classDef deployment fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px;
    classDef config fill:#FFF8E1,stroke:#F9A825,stroke-width:2px;

    %% Legend
    subgraph Legend
        direction TB
        L1["UI Components"]:::ui
        L2["Hooks/State"]:::hooks
        L3["Service Wrappers"]:::service
        L4["Utilities"]:::utils
        L5["Mock Data"]:::mock
        L6["External Services"]:::external
        L7["Deployment & Config"]:::deployment
    end
```
