How parvez-ahammed/pc-tracker works
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.