# yl1183/laformula architecture

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

- Interactive diagram: https://gitdiagram.com/yl1183/laformula
- Repository: https://github.com/yl1183/laformula

## Overview

##### Project Type and Purpose
- LaFormula is a full-stack application combined with an ETL pipeline.

##### File-Structure Analysis
- Top-level scripts (extract.py, transform.py, load.py, update.py, web_scrape.py, load_google_connector.py, main.py, service.py, datamodels.py, sql_side/):
- These implement the ETL/data-ingestion and utility tasks.
- laformula_backend/:
- A Django project (“laformula”) with one app (“test_app”).
- Contains models.py, serializers.py, views.py → implements MVC/REST API.
- Settings, URLs, ASGI/WGSI for deployment.
- laformula_frontend/:
- A React project (create-react-app structure) under src/, public/.
- Components/, pages/ for UI; api.js for HTTP calls to the Django backend.
- Other artifacts: manual_test.ipynb for exploratory analysis; sql_side/ for raw SQL or DDL scripts.

##### Key Insights from README
- Ranking “best driver” independent of car performance.
- A reference ERD link suggests a relational data model in the database.
- Screenshot hints at a homepage slider and data tables – features implemented in React.

##### Main Components & Their Interactions
a. Data Ingestion Layer (ETL)
- Components: web_scrape.py, load_google_connector.py
- Function: Pull raw race and driver data from external sources.
b. Transformation Layer
- Components: transform.py, datamodels.py
- Function: Clean, normalize, and map raw data into schema.
c. Loading Layer
- Components: load.py, update.py, sql_side/
- Function: Insert/update records in the relational database (as defined by Django models).
d. Database
- Likely PostgreSQL/SQLite configured in Django settings.py
- Holds tables for drivers, races, results, computed rankings.
e. Backend API (Django MVC/REST)
- laformula_backend/laformula: project settings & URL routing.
- test_app: models.py, serializers.py (data → JSON), views.py (API endpoints).
- Exposes endpoints consumed by frontend.
f. Frontend UI (React SPA)
- laformula_frontend/src: components (DriverGrid, HomepageSlider, Navbar, etc.), pages (Home, Drivers, Races, Teams).
- api.js: defines REST calls to backend.
- Renders interactive visualizations and dropdowns using fetched JSON data.

##### Architectural Patterns & Design Principles
- ETL pipeline pattern (Extract → Transform → Load) separated into distinct scripts.
- MVC / REST paradigm in backend: clear separation of models, serializers, and views/controllers.
- Single-page application on frontend: component-based, unidirectional data flow (props/state).
- Modularization: separate directories for scripts, backend, frontend.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    subgraph "External Data Sources" 
        direction TB
        Web["Web Pages"]:::external
        GoogleSheets["Google Sheets API"]:::external
    end

    %% ETL Extraction Layer
    subgraph "ETL Extraction Layer" 
        direction TB
        ExtractOrch["main.py / service.py / extract.py"]:::dataProcessing
        WebScrape["web_scrape.py"]:::dataProcessing
        LoadGoogle["load_google_connector.py"]:::dataProcessing
    end

    %% Transformation Layer
    subgraph "Transformation Layer" 
        direction TB
        Transform["transform.py"]:::dataProcessing
        DataModels["datamodels.py"]:::dataProcessing
    end

    %% Loading Layer
    subgraph "Loading Layer" 
        direction TB
        LoadScript["load.py"]:::dataProcessing
        UpdateScript["update.py"]:::dataProcessing
        SQLSide["sql_side/"]:::dataProcessing
    end

    %% Database
    DB[(Database)]:::storage

    %% Backend API Layer
    subgraph "Django API (Backend)" 
        direction TB
        subgraph "Project Configuration"
            direction TB
            Settings["settings.py"]:::backend
            URLs["urls.py"]:::backend
            ASGI["asgi.py"]:::backend
            WSGI["wsgi.py"]:::backend
            Manage["manage.py"]:::backend
        end
        subgraph "test_app"
            direction TB
            Models["models.py"]:::backend
            Serializers["serializers.py"]:::backend
            Views["views.py"]:::backend
            Admin["admin.py"]:::backend
            Migrations["0001_initial.py"]:::backend
        end
    end

    %% Frontend UI Layer
    subgraph "React Frontend UI" 
        direction TB
        subgraph "Entry & Config"
            direction TB
            Index["index.js"]:::frontend
            AppJS["App.js"]:::frontend
            APIJS["api.js"]:::frontend
        end
        subgraph "Components"
            direction TB
            Slider["homepage_slider.js"]:::frontend
            DriverGrid["drivergrid.js"]:::frontend
            Navbar["navbar.js"]:::frontend
            LoadingCar["loading_car.js"]:::frontend
            ResultParents["resultparents.js"]:::frontend
            ResultChild["resultchild.js"]:::frontend
            ResultsDropdown["resultsdropdown.js"]:::frontend
            CircuitStats["circuitstats.js"]:::frontend
        end
        subgraph "Pages"
            direction TB
            HomePage["Home.js"]:::frontend
            DriversPage["Drivers.js"]:::frontend
            RacesPage["Races.js"]:::frontend
            TeamsPage["Teams.js"]:::frontend
            AboutPage["About.js"]:::frontend
        end
    end

    %% Analysis Sandbox
    ManualTest["manual_test.ipynb"]:::external

    %% Data Flows
    Web -->|"Raw HTML"| WebScrape
    GoogleSheets -->|"Raw Data"| LoadGoogle
    ExtractOrch -->|coordinates| WebScrape
    ExtractOrch -->|coordinates| LoadGoogle
    WebScrape -->|"Extracted Data"| Transform
    LoadGoogle -->|"Extracted Data"| Transform
    Transform -->|"Transformed Data"| LoadScript
    Transform -->|"Transformed Data"| UpdateScript
    LoadScript -->|"SQL INSERT"| DB
    UpdateScript -->|"SQL UPDATE"| DB
    SQLSide -->|"DDL Scripts"| DB
    DB -->|"ORM"| Models
    Models -->|"Data Access"| Views
    Views -->|"JSON Responses"| APIJS
    APIJS -->|"HTTP GET/POST"| Views
    Views -->|"API Endpoints"| HomePage
    HomePage --> DriversPage
    HomePage --> RacesPage
    HomePage --> TeamsPage
    HomePage --> AboutPage
    DriversPage --> DriverGrid
    RacesPage --> ResultsDropdown
    TeamsPage --> CircuitStats
    ManualTest -->|"Query Data"| DB

    %% Click Events
    click WebScrape "https://github.com/yl1183/laformula/blob/main/web_scrape.py"
    click LoadGoogle "https://github.com/yl1183/laformula/blob/main/load_google_connector.py"
    click Transform "https://github.com/yl1183/laformula/blob/main/transform.py"
    click DataModels "https://github.com/yl1183/laformula/blob/main/datamodels.py"
    click LoadScript "https://github.com/yl1183/laformula/blob/main/load.py"
    click UpdateScript "https://github.com/yl1183/laformula/blob/main/update.py"
    click SQLSide "https://github.com/yl1183/laformula/tree/main/sql_side/"
    click ExtractOrch "https://github.com/yl1183/laformula/blob/main/main.py"
    click ExtractOrch "https://github.com/yl1183/laformula/blob/main/service.py"
    click ExtractOrch "https://github.com/yl1183/laformula/blob/main/extract.py"
    click Settings "https://github.com/yl1183/laformula/blob/main/laformula_backend/laformula/settings.py"
    click URLs "https://github.com/yl1183/laformula/blob/main/laformula_backend/laformula/urls.py"
    click ASGI "https://github.com/yl1183/laformula/blob/main/laformula_backend/laformula/asgi.py"
    click WSGI "https://github.com/yl1183/laformula/blob/main/laformula_backend/laformula/wsgi.py"
    click Manage "https://github.com/yl1183/laformula/blob/main/laformula_backend/manage.py"
    click Models "https://github.com/yl1183/laformula/blob/main/laformula_backend/test_app/models.py"
    click Serializers "https://github.com/yl1183/laformula/blob/main/laformula_backend/test_app/serializers.py"
    click Views "https://github.com/yl1183/laformula/blob/main/laformula_backend/test_app/views.py"
    click Admin "https://github.com/yl1183/laformula/blob/main/laformula_backend/test_app/admin.py"
    click Migrations "https://github.com/yl1183/laformula/blob/main/laformula_backend/test_app/migrations/0001_initial.py"
    click Index "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/index.js"
    click AppJS "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/App.js"
    click APIJS "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/api.js"
    click Slider "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/homepage_slider.js"
    click DriverGrid "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/drivergrid.js"
    click Navbar "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/navbar.js"
    click LoadingCar "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/loading_car.js"
    click ResultParents "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/resultparents.js"
    click ResultChild "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/resultchild.js"
    click ResultsDropdown "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/resultsdropdown.js"
    click CircuitStats "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/components/circuitstats.js"
    click HomePage "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/pages/Home.js"
    click DriversPage "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/pages/Drivers.js"
    click RacesPage "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/pages/Races.js"
    click TeamsPage "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/pages/Teams.js"
    click AboutPage "https://github.com/yl1183/laformula/blob/main/laformula_frontend/src/pages/About.js"

    %% Styles
    classDef dataProcessing fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef storage fill:#C8E6C9,stroke:#2e7d32,color:#2e7d32
    classDef backend fill:#FFE0B2,stroke:#ef6c00,color:#ef6c00
    classDef frontend fill:#E1BEE7,stroke:#8e24aa,color:#8e24aa
    classDef external fill:#FFCCBC,stroke:#d84315,color:#d84315
```
