# tan-oi/tracker architecture

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

- Interactive diagram: https://gitdiagram.com/tan-oi/tracker
- Repository: https://github.com/tan-oi/tracker

## Overview

##### Project Type and Core Purpose
- This is a full-stack web application that aggregates contest data from multiple competitive programming platforms (LeetCode, CodeChef, Codeforces).
- Its main functionality is to display upcoming and past contests, provide filtering options, manage bookmarks locally, and incorporate solution video links fetched both manually and via automated processes.
- The platform includes both a frontend (built with React/Vite) and a backend (built using Express.js, with Node-cron for scheduled tasks and MongoDB as the database).

##### Main System Components
A. Frontend (React + Vite):
- Contains all UI elements, including reusable components (contest cards, navbar, filter bar, dialogs, etc.).
- Manages client-side state with localStorage (for bookmarks and JWT authentication) and may later use state management libraries (Zustand/React-Query) as mentioned in the README.
- Interacts with the backend via RESTful APIs.

B. Backend (Express.js Server):
- Organized with a clear separation of concerns:
- Controllers: Handling API requests for contest retrieval, video addition, and admin access.
- Routes: Defining endpoints (like /contests, /leetcode, /codechef, /codeforces, /addVideo, /access).
- Services: Encapsulate business logic such as fetching contest data from external coding platforms, updating contest statuses, and integrating with the YouTube API.
- Middlewares: Includes authentication checks and other request validations (e.g., checkUser.ts for admin verification).
- Database Integration: Although not explicitly visible in the file tree, the existence of a “db.ts” file indicates connection logic (MongoDB).
- Cron Jobs: Automated scripts (found in src/scripts and services) manage periodic data fetching and updates.

C. External Services & APIs:
- Coding contest APIs on LeetCode, CodeChef, and Codeforces.
- YouTube API for fetching video links for contest solutions.
- Cron mechanism using “node-cron” for scheduled updates.

##### Relationships and Data Flow
- Frontend → Backend: The UI makes API calls to the backend to fetch contest lists, filtered data, and to perform admin actions such as adding video links.
- Backend → Database: The Express server reads from and writes contest data to MongoDB, while implementing security measures like JWT authentication.
- Backend → External APIs: Services in the backend periodically fetch new contest data and solution video links, with workflows initiated by cron jobs.
- User Authentication: When an admin authentically adds video links, the backend validates the secret key and issues JWT tokens, which the frontend stores and uses to maintain sessions.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Controllers handle incoming requests, services encapsulate business logic, and middleware provides reusability (e.g., authorization).
- Layered Architecture: The system is organized into distinct layers (UI layer, API gateway, business logic, data persistence, external communication) that communicate via clear interfaces.
- Scheduled Tasks: Use of cron jobs for background processing to keep contest data up to date.
- Consistent API Design: RESTful endpoints grouped under meaningful routes (exposing contest data and admin-specific functionalities).

– Users/Clients interacting with the Frontend.
– The Frontend connecting to the Backend API.
– The Backend comprising:
- API Controllers & Routes.
- Service Layer (includes modules for contest fetching, video updates, admin access).
- Middleware (authentication, request validations).
– A separate component for the Database (MongoDB).
– External Services (Coding Contest APIs and YouTube API) connected to backend services.
– Scheduled Cron Job module triggering service updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users/Clients
    U["Users"]:::user

    %% Frontend Subgraph
    subgraph "Frontend"
        F1["Frontend (React + Vite)"]:::frontend
        F2["Admin Video Interface"]:::frontend
        F3["Reusable UI Components"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend"
        B1["Express Server"]:::backend
        subgraph "Backend Components"
            B2["Controllers"]:::backend
            B3["Routes"]:::backend
            B4["Middlewares"]:::backend
            B5["Services"]:::backend
        end
        DB["MongoDB (Database)"]:::database
        C1["Cron Jobs Scheduler"]:::backend
    end

    %% External Services Subgraph
    subgraph "External Services"
        E1["Coding Contest APIs"]:::external
        E2["YouTube API"]:::external
    end

    %% Connections
    U -->|"interacts"| F1
    U -->|"interacts"| F2

    F1 -->|"API_call"| B1
    F2 -->|"Admin_API_call"| B1

    B1 -->|"delegates"| B2
    B1 -->|"delegates"| B3
    B1 -->|"delegates"| B4
    B1 -->|"delegates"| B5

    B5 -->|"reads/writes"| DB
    B5 -->|"fetches"| E1
    B5 -->|"fetches"| E2

    C1 -->|"triggers"| B5

    %% Click Events
    click F1 "https://github.com/tan-oi/tracker/tree/main/frontend/src/components"
    click F2 "https://github.com/tan-oi/tracker/blob/main/frontend/src/AdminVideoAccess.tsx"
    click F3 "https://github.com/tan-oi/tracker/tree/main/frontend/src/components"
    click B1 "https://github.com/tan-oi/tracker/blob/main/backend/src/index.ts"
    click B2 "https://github.com/tan-oi/tracker/tree/main/backend/src/controllers"
    click B3 "https://github.com/tan-oi/tracker/tree/main/backend/src/routes"
    click B4 "https://github.com/tan-oi/tracker/tree/main/backend/src/middlewares"
    click B5 "https://github.com/tan-oi/tracker/tree/main/backend/src/services"
    click DB "https://github.com/tan-oi/tracker/blob/main/backend/src/db.ts"
    click C1 "https://github.com/tan-oi/tracker/tree/main/backend/src/scripts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef database fill:#90EE90,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef user fill:#F5DEB3,stroke:#333,stroke-width:2px;
```
