# parvez-ahammed/pc-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/parvez-ahammed/pc-tracker
- Repository: https://github.com/parvez-ahammed/pc-tracker

## Overview

##### Project Type and Purpose
- This is a full-stack application that tracks programming contest performance for AUST’s teams.
- The README highlights key features such as summaries of contests, downloading contest details, and listings of contestants.
- The project combines a React/TypeScript frontend (in the src directory) with a Python-based scrapper module (in the Scrapper folder) that appears to gather contest data from various sources.
- Docker and Docker Compose files indicate containerization for easier deployment.

##### File Structure to Identify Main Components and Architectural Choices
- Frontend (React Application):
- The src folder contains the main application files including:
◦ App.tsx, pages (e.g., LandingPage.tsx), routes (Router.tsx), and providers.
◦ Feature subdirectories (contestants, contests) each with their own components, hooks, constants, and interfaces.
◦ Adapters in src/adapters (e.g., csvToJson.tsx, jsonToMap.tsx) suggest conversion utilities for data transformation.
- Public assets such as index.html, styling, and images to render the user interface.
- Data Scrapping Component:
- The Scrapper directory holds Python scripts (HTML_Parser.py, Contest_Details.py, Toph_Scrapper.py, etc.) that likely fetch and process contest data.
- There is also an IUPC_DATA.json file which might store scraped contest-related data.
- Auxiliary Files:
- Dockerfile, docker-compose.yml, and example.env allow the project to be containerized and deployed easily.
- Configuration files (package.json, tsconfig*, vite.config.ts, .eslintrc.cjs) indicate modern JavaScript tooling and linting settings.
- Git/GitHub related files (CONTRIBUTING.md, LICENSE, CODE_OF_CONDUCT.md) reinforce that this is a community-friendly project.

a. Main Components:
- User Interface (Frontend):
- React Application: Core UI components, pages, routes, providers.
- Feature Modules: Separate sections for “contests” and “contestants”, each with its own set of UI components and logic.
- Adapters & Utilities: For data transformations (e.g., CSV to JSON).
- Data Scrapper Module:
- Python Scripts: Represented as a “Scrapper” block handling data extraction via modules like Contest_Details.py and Toph_Scrapper.py.
- Data Store/File: JSON file (IUPC_DATA.json) acting as an intermediary data store.
- Deployment Infrastructure:
- Docker Containers: Use a container for the frontend application and another for the scrapper (if they are run as separate services), as indicated by the Dockerfile and docker-compose.yml.
- Optional Backend Components: If the public/main.py (in the public folder) or other files are meant as a lightweight API or server, include that as a separate service.

b. Relationships and Data Flows:
- Interconnections between the UI’s individual components (e.g., from the Router to pages, from pages to feature components).

c. Architectural Patterns and Design Principles:
- Modularization: Clearly separate the concerns (frontend UI vs. data scraping logic).
- Component-Based Design: For the React application, highlight that components are grouped by features (contests, contestants).
- Data Transformation: Emphasize the use of adapters in converting data (CSV/JSON) for the UI.
- Containerization: Use Docker to ensure environment consistency; represent how each main component runs inside its own container.

d. Technologies and Libraries:
- Frontend: React with TypeScript, Vite for building, CSS for styling.
- Data Scraping: Python scripts with libraries for web scraping and HTML parsing.
- Containerization and Environment: Docker, Docker Compose.
- Utility Tools: ESLint for linting, various configuration files indicating build and deployment tooling.

##### Final Advice
- Be detailed: Aim to capture every significant part of the project’s structure.
- Don’t oversimplify by lumping everything together; break the project down into as many clear, well-defined components as possible.
- This detailed view not only improves clarity on how the system works but also aids in future planning and debugging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        ReactUI["React Application (UI)"]:::frontend
        Adapters["Data Transformation Adapters"]:::frontend
        Contests["Feature Module - Contests"]:::frontend
        Contestants["Feature Module - Contestants"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Scrapper["Python Data Scrapper Module"]:::backend
        DataStore(("IUPC_DATA.json")):::datastore
        API["Lightweight API/Server"]:::backend
    end

    %% Deployment Infrastructure
    Infra["Containerization (Docker)"]:::deploy

    %% Data Flow Connections
    Scrapper -->|"scrapes"| DataStore
    DataStore -->|"feeds"| Adapters
    Adapters -->|"transforms"| ReactUI
    ReactUI -->|"renders"| Contests
    ReactUI -->|"renders"| Contestants
    ReactUI -->|"calls API"| API

    %% Deployment Relationships
    Infra -.-> Scrapper
    Infra -.-> ReactUI
    Infra -.-> API

    %% Click Events
    click ReactUI "https://github.com/parvez-ahammed/pc-tracker/blob/main/src/App.tsx"
    click Contests "https://github.com/parvez-ahammed/pc-tracker/tree/main/src/features/contests"
    click Contestants "https://github.com/parvez-ahammed/pc-tracker/tree/main/src/features/contestants"
    click Adapters "https://github.com/parvez-ahammed/pc-tracker/tree/main/src/adapters"
    click Scrapper "https://github.com/parvez-ahammed/pc-tracker/tree/main/Scrapper"
    click DataStore "https://github.com/parvez-ahammed/pc-tracker/blob/main/Scrapper/IUPC_DATA.json"
    click Infra "https://github.com/parvez-ahammed/pc-tracker/tree/main/Dockerfile"
    click API "https://github.com/parvez-ahammed/pc-tracker/blob/main/public/main.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef datastore fill:#E0BBE4,stroke:#000,stroke-width:2px;
    classDef deploy fill:#FFD700,stroke:#000,stroke-width:2px;
```
