# steventanyang/ufcraxv2 architecture

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

- Interactive diagram: https://gitdiagram.com/steventanyang/ufcraxv2
- Repository: https://github.com/steventanyang/ufcraxv2

## Overview

##### Project Type and Purpose
- This appears to be a full-stack application focused on processing and visualizing data related to UFC fights and fighters.
- The project uses Python scripts to process raw fight/fighter CSV data, and then the processed output (in CSV/JSON form) is utilized by a Next.js frontend to display insights, comparisons, calendars, and recommendations.

##### Analyzing the File Structure
- Top-Level Organization:
– Core configuration files include package.json, Next.js-specific configs (next.config.ts), and Tailwind/TypeScript configurations.
– The “src” directory contains the main frontend application. It is organized into application-level files, shared components (e.g., FighterComparison, FighterCalendar), hooks (e.g., useDebounce), types, and utility functions.
– The “python” directory formalizes the data processing backend. Along with its own README and requirements.txt, it contains a pipeline script, several independent scripts for tasks like data aggregation, duplications removal, and processing matches.
– Raw data is stored in both the “data” directory and within the “python/data” folder, while processed results are saved to “python/results” and “public/data” (the latter being exposed for frontend consumption).

- Key Components:
– Frontend (UI):
- “src” folder represents the Next.js based frontend.
- Components include pages, modals (e.g., ChangelogModal, FighterModal), interactive calendars, search bars, and recommendation widgets.
– Data Processing Layer (Backend):
- “python” folder contains the pipeline, processing scripts, and related configurations.
- This module handles data cleaning, aggregation, and transformation to produce meaningful outputs.
– Data Stores:
- Raw Data: The “data” and “python/data” directories hold the input CSV and JSON files.
- Processed Data: Results are stored in “python/results” and then exposed to the UI via static assets in “public/data”.
– Configuration & Build:
- Config files for ESLint, Tailwind, and TypeScript as well as Next.js configuration integrate the project across both frontend and processing layers.

- Elaborate on the Relationships and Interactions:
– The data ingestion process involves reading raw data files (CSV/JSON) from the designated directories.
– Python scripts (pipeline and individual scripts) process these files and output transformed data. Results might then be copied or linked to the “public/data” folder.
– The Next.js frontend, running via “npm run dev”, serves interactive components that consume these processed JSON/CSV files.
– There can be an API or direct static file serving mechanism (via Next.js public assets) that bridges the processed data to the UI components.

- Architectural Patterns and Design Principles:
– Separation of Concerns: Clear demarcation between data processing (Python backend) and frontend presentation (Next.js React components).
– Modular Design: Python scripts are modular, each performing discrete tasks (aggregation, deduplication, value calculations); similarly, frontend components are compartmentalized.
– Integration Point: The public folder acts as the integration point where processed data is shared from the backend to the frontend.

- Relevant Technologies:
– Frontend: Next.js, React (in TypeScript), Tailwind CSS for styling.
– Data Processing: Python with various standalone scripts, CSV/JSON handling, and pipelining logic (as seen in pipeline.py).
– Build/Config Tools: ESLint, TypeScript, and Node package management.

##### Specific Elements
- Clear Labels: Name each component (e.g., “Data Pipeline (Python)”, “Frontend Application (Next.js)”, “Raw Data Store”, “Processed Data Store”).
- Modules within the Python backend: Show the “pipeline.py” as the orchestrator and include auxiliary scripts that perform specific processing tasks.
- Use of APIs/Static File Serving: Indicate how the frontend retrieves data from “public/data”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        A1["Python Raw Data (python/data)"]:::data
        A2["Additional Raw Data (data)"]:::data
        A3["Processed Data (python/results)"]:::data
        A4["Public Data Assets (public/data)"]:::data
    end

    %% Processing Layer
    subgraph "Processing Layer"
        P1["Data Processing Pipeline (Python)"]:::backend
        P2["Python Processing Scripts"]:::backend
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        F1["Frontend Application (Next.js UI)"]:::frontend
        F2["Frontend Pages & Layouts (src/app)"]:::frontend
        F3["Reusable Frontend Components (src/components/)"]:::frontend
        F4["Custom React Hooks (useDebounce)"]:::frontend
        F5["Type Definitions (src/types/)"]:::frontend
        F6["Utility Functions (src/utils/)"]:::frontend
        F7["Project Config & Build Files"]:::frontend
    end

    %% Data Flow Connections
    A1 -->|"input"| P1
    A2 -->|"input"| P1
    P1 -->|"orchestrates"| P2
    P2 -->|"outputs results"| A3
    A3 -->|"copies to"| A4
    A4 -->|"consumed by"| F1

    %% Frontend Internal Dependencies
    F1 -->|"uses"| F2
    F1 -->|"uses"| F3
    F1 -->|"uses"| F4
    F1 -->|"uses"| F5
    F1 -->|"uses"| F6
    F1 -->|"uses"| F7

    %% Click Events for Data Layer
    click A1 "https://github.com/steventanyang/ufcraxv2/tree/main/python/data/"
    click A2 "https://github.com/steventanyang/ufcraxv2/tree/main/data/"
    click A3 "https://github.com/steventanyang/ufcraxv2/tree/main/python/results/"
    click A4 "https://github.com/steventanyang/ufcraxv2/tree/main/public/data/"

    %% Click Events for Processing Layer
    click P1 "https://github.com/steventanyang/ufcraxv2/blob/main/python/pipeline.py"
    click P2 "https://github.com/steventanyang/ufcraxv2/tree/main/python/scripts/"

    %% Click Events for Presentation Layer
    click F1 "https://github.com/steventanyang/ufcraxv2/tree/main/src/"
    click F2 "https://github.com/steventanyang/ufcraxv2/tree/main/src/app"
    click F3 "https://github.com/steventanyang/ufcraxv2/tree/main/src/components/"
    click F4 "https://github.com/steventanyang/ufcraxv2/blob/main/src/hooks/useDebounce.ts"
    click F5 "https://github.com/steventanyang/ufcraxv2/tree/main/src/types/"
    click F6 "https://github.com/steventanyang/ufcraxv2/tree/main/src/utils/"
    click F7 "https://github.com/steventanyang/ufcraxv2/blob/main/package.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef data fill:#FFFACD,stroke:#333,stroke-width:2px;
```
