# lhmson/mini-contest-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/lhmson/mini-contest-tracker
- Repository: https://github.com/lhmson/mini-contest-tracker

## Overview

##### Project Type & Purpose
- This is a full-stack application combining a React-based, TypeScript frontend (using Redux Toolkit, Material-UI, React Query, etc.) with a backend API component (likely an Express/Node.js server) to handle contest data and various integrations.
- There is also evidence of browser extension elements (manifest.json and background.js) which may indicate additional ways to interact with the service.

##### Analyzing the File Structure
- Frontend (client-side):
- The main client lives under the “src” directory – it includes UI components (in “src/components”), pages, custom hooks, services (for contests, reminders, and YouTube interactions), and global state management (under “src/store”).
- The “src/assets”, “src/types”, “src/utils” directories and the presence of various configuration files (e.g., vite.config.js/ts) indicate a well-organized, modular React application.
- Backend/API:
- The “api” folder and server.js files (both at the root and within “api”) suggest an Express-based (or similar) Node.js server handling API endpoints and possibly server-side operations such as sending reminders.
- Vercel configuration files (vercel.json in both the project root and inside “api”) indicate deployment setups for serverless or hosting environments.
- Additional Components:
- Files like “manifest.json” and “background.js” point towards a browser extension-style integration, which could be an additional front-facing component that interacts with the main service.

##### Key Components
a. Frontend Client:
- React UI: The “src” directory components, hooks, and state management (Redux store).
- Styling/Theming: Components like ThemeWrapper and usage of Material-UI & Styled Components.
- Data Integration: Services for contests, YouTube, and reminders which connect to the backend.
b. API/Backend Server:
- Node.js server(s) found in “api” and server.js at the root.
- Endpoints serving contest data, handling user interactions, and managing external service integrations (emails, SMS, YouTube).
c. Browser Extension (if applicable):
- Components defined by “manifest.json” and “background.js” that may provide extra functionality or notifications on the browser side.
d. External Services:
- YouTube API (for solution video integration).
- Email and SMS service providers (for sending contest reminders).
e. Deployment & Build Tools:
- Build configurations (Vite, tsconfig, eslint, prettier, etc.).
- Deployment specifics via vercel.json for hosting the API and possibly serverless functions.

##### Relationships and Interactions
- The Frontend client interacts with the Backend API:
- The API server communicates with external services:
- Browser Extension (if present):
- Deployment and Build Tools:
- Build pipelines (scripts in “scripts”) preparing both the frontend and backend, and point to deployment targets (Vercel).

##### Architectural Patterns & Design Principles
- Separation of concerns: Clearly separate the frontend (React, Redux) from the backend (Node.js API) and the external service integrations.
- Modularity: Emphasize how different TypeScript modules (services, hooks, utilities) and folders work together within the client.
- Scalability: Indicate that API endpoints and external integrations can be scaled, especially considering the deployment configuration with Vercel.
- If applicable (for the browser extension), highlight the extension’s isolated but connected nature, ensuring that notifications and background tasks are separately managed.

##### Instructing the Principal Software Engineer
- That every component (frontend, backend, possibly browser extension, and external integrations) has a clear and separate representation.
– How the user interacts with the React UI and how state is managed with Redux.
– The API server that acts as the intermediary with external services.
– The integration with services such as YouTube, email, and SMS providers.
– Deployment and configuration details (through vercel.json and build tools) that affect both client and server.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    User["User/Browser"]:::external

    %% Frontend Subgraph
    subgraph "Frontend"
        React["React Client"]:::frontend
        Theme["Theme Styling"]:::frontend
        subgraph "Services"
            ContestService1["contestService"]:::service
            YouTubeService["youtubeService"]:::service
            ReminderService["reminderService"]:::service
        end
    end

    %% Backend/API Server
    Backend["API Server"]:::backend

    %% Browser Extension Subgraph
    subgraph "Browser Extension"
        Manifest["Manifest"]:::extension
        Background["Background Script"]:::extension
    end

    %% External Services
    YtAPI["YouTube API"]:::external
    EmailSMS["Email/SMS Providers"]:::external

    %% Deployment and Utility
    Deployment["Deployment & Build Tools"]:::deployment
    Utility["Utility Scripts"]:::utility

    %% Connections and Relationships
    User -->|"uses"| React
    React -->|"applies"| Theme
    React -->|"calls"| ContestService1
    React -->|"calls"| YouTubeService
    React -->|"calls"| ReminderService
    React -->|"APICall"| Backend

    Manifest -->|"communicates"| Backend
    Background -->|"communicates"| Backend
    %% Optionally, Browser Extension interacts with Frontend
    Manifest -->|"notifies"| React
    Background -->|"notifies"| React

    Backend -->|"fetchesVideo"| YtAPI
    Backend -->|"sendsReminder"| EmailSMS

    Deployment -->|"builds/deploys"| React
    Deployment -->|"builds/deploys"| Backend
    Utility -->|"runs"| Deployment

    %% Click Events
    click React "https://github.com/lhmson/mini-contest-tracker/tree/main/src/"
    click Theme "https://github.com/lhmson/mini-contest-tracker/blob/main/src/components/ThemeWrapper.tsx"
    click ContestService1 "https://github.com/lhmson/mini-contest-tracker/blob/main/src/services/contestService.ts"
    click YouTubeService "https://github.com/lhmson/mini-contest-tracker/blob/main/src/services/youtubeService.ts"
    click ReminderService "https://github.com/lhmson/mini-contest-tracker/blob/main/src/services/reminderService.ts"
    click Backend "https://github.com/lhmson/mini-contest-tracker/tree/main/api/"
    click Manifest "https://github.com/lhmson/mini-contest-tracker/blob/main/manifest.json"
    click Background "https://github.com/lhmson/mini-contest-tracker/blob/main/background.js"
    click Deployment "https://github.com/lhmson/mini-contest-tracker/blob/main/vite.config.js/vite.config.ts"
    click Utility "https://github.com/lhmson/mini-contest-tracker/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef extension fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef deployment fill:#AFEEEE,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFFACD,stroke:#333,stroke-width:2px;
```
