# qv1ko/racingtracker architecture

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

- Interactive diagram: https://gitdiagram.com/qv1ko/racingtracker
- Repository: https://github.com/qv1ko/racingtracker

## Overview

##### Project Type and Purpose
- This is a full-stack web application called “RacingTracker,” built on Laravel 12 (PHP 8.2) for the backend and React (via Inertia.js & Vite) for the frontend.
- It provides CRUD management of Drivers, Teams, Races, and Participations, and computes a dynamic scoring system based on driver performance.

##### Main Components
a. Client-side (Browser)
- React UI (resources/js) built with TailwindCSS & Vite
- Inertia.js pages and components for routing and state hydration
b. Web Server
- Nginx (or built-in PHP server) serving index.php
- PHP-FPM processing Laravel requests
c. Application Layer (Laravel)
- HTTP Controllers (app/Http/Controllers) implementing REST endpoints
- Request Validation (app/Http/Requests)
- Models & Eloquent ORM (app/Models) mapping to database tables
- Business logic for scoring (services under app/… if factored out)
- Inertia Middleware bridging Laravel and React
d. Data Layer
- SQLite (config/database.php) or other relational DB
- Migrations & Seeders (database/)
e. Persistent Storage
- File System (storage/) for logs, caches, uploaded files
f. External Services
- Mail API (config/mail.php) for email verification and notifications
- (Optional) AWS S3 or other cloud storage if configured

##### Interactions and Data Flow
- Browser → Nginx: HTTP requests (static assets or /index.php)
- Nginx → PHP-FPM → Laravel Router → Controller
- Controller → Request Validation → Eloquent Model → Database
- Controller → Inertia Response → React components rendered client-side
- React UI → API calls via Inertia for dynamic data updates
- Laravel Events/Jobs (queue.php) → Mailer for email notifications
- Laravel Scheduler or Jobs → background tasks (if any)

##### Architectural Patterns and Design Principles
- MVC pattern on the server side (Models, Views via Inertia, Controllers)
- Single-Page Application feel via Inertia.js (no separate API layer)
- Convention-over-configuration (Laravel folder structure)
- Modular React components under resources/js/components and layouts
- Environment-driven configuration (.env)
- CI workflows for linting & tests (.github/workflows)

##### Technologies and Frameworks to Highlight
- Backend: Laravel 12 on PHP 8.2, Eloquent ORM, SQLite (or MySQL/PostgreSQL), Inertia.js
- Frontend: React 16.8+, Vite, TypeScript, TailwindCSS
- DevOps: Composer, npm, GitHub Actions, dotenv, phpunit, Pest
- Deployment: Nginx + PHP-FPM, optional AWS EC2, VPC, IAM for deploy user

- Incorporate the Inertia layer explicitly between Controllers and React
- A Deployment inset showing Nginx + PHP-FPM on EC2 within a VPC
- Dynamic scoring computation as a service process invoked by Controller → Model
- CI/CD workflows as an auxiliary component feeding into the Repo → Build → Deploy path

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        ReactUI["React UI (TailwindCSS & Vite)"]:::frontend
        InertiaPages["Inertia.js Pages & Routing"]:::frontend
        ReactComponents["React Components Library"]:::frontend
        Layouts["Global & Auth Layouts"]:::frontend
        Hooks["Client-side Hooks & Utilities"]:::frontend
        Types["Frontend Types"]:::frontend
        SSREntry["SSR Entry Point"]:::frontend
        ViteConfig["Vite Configuration"]:::frontend
        BladeView["Main Blade View"]:::frontend
    end

    %% Web Server Layer
    subgraph "Web Server & PHP-FPM"
        direction TB
        Nginx["Nginx"]:::backend
        PHPFPM["PHP-FPM"]:::backend
    end

    %% Laravel Application Layer
    subgraph "Laravel Application"
        direction TB
        Controllers["HTTP Controllers"]:::backend
        InertiaMiddleware["Inertia Middleware"]:::backend
        Requests["Request Validation"]:::backend
        Models["Eloquent Models"]:::backend
        ScoringSvc["Scoring Service"]:::backend
        ConfigInertia["Inertia Config"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["Database"]:::database
        Migrations["Migrations"]:::database
        Seeders["Seeders & Factories"]:::database
        DBConfig["DB Configuration"]:::backend
    end

    %% Storage
    subgraph "Persistent Storage"
        direction TB
        FileStorage["File System Storage"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MailAPI["Mail API"]:::external
    end

    %% Deployment Inset
    subgraph "AWS Deployment"
        direction TB
        VPC["VPC"]:::external
        EC2["EC2 Instance"]:::external
        Security["Security Group"]:::external
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        Repo["GitHub Repo"]:::external
        Lint["Lint Workflow"]:::external
        Tests["Tests Workflow"]:::external
        Build["Build & Deploy"]:::external
    end

    %% Connections
    ReactUI -->|"HTTP (assets & index)| Nginx
    BladeView -->|"Served via| Nginx
    Nginx -->|"FastCGI"| PHPFPM
    PHPFPM -->|"Laravel Request"| Controllers
    Controllers -->|"validate"| Requests
    Controllers -->|"ORM calls"| Models
    Models -->|"SQL queries"| DB
    Controllers -->|"Inertia Response"| ReactUI
    ReactUI -->|"Inertia Visits"| Controllers
    Controllers -->|"compute score"| ScoringSvc
    ScoringSvc -->|"reads/writes"| Models
    Controllers -->|"use middleware"| InertiaMiddleware
    Controllers -->|"use config"| ConfigInertia
    DBConfig --> DB
    Migrations --> DB
    Seeders --> DB
    FileStorage --> Controllers
    Controllers -->|--- SMTP/HTTP | MailAPI
    Repo -->|push| Lint
    Repo -->|push| Tests
    Tests -->|on success| Build
    Build -->|deploy| EC2
    EC2 -->|in| VPC
    EC2 -->|secured by| Security

    %% Click Events
    click ReactUI "https://github.com/qv1ko/racingtracker/tree/main/resources/js"
    click InertiaPages "https://github.com/qv1ko/racingtracker/tree/main/resources/js/pages"
    click ReactComponents "https://github.com/qv1ko/racingtracker/tree/main/resources/js/components"
    click Layouts "https://github.com/qv1ko/racingtracker/tree/main/resources/js/layouts"
    click Hooks "https://github.com/qv1ko/racingtracker/tree/main/resources/js/hooks"
    click Hooks "https://github.com/qv1ko/racingtracker/blob/main/resources/js/lib/utils.ts"
    click Types "https://github.com/qv1ko/racingtracker/tree/main/resources/js/types"
    click SSREntry "https://github.com/qv1ko/racingtracker/blob/main/resources/js/ssr.tsx"
    click ViteConfig "https://github.com/qv1ko/racingtracker/blob/main/vite.config.ts"
    click BladeView "https://github.com/qv1ko/racingtracker/blob/main/resources/views/app.blade.php"
    click Controllers "https://github.com/qv1ko/racingtracker/tree/main/app/Http/Controllers"
    click Requests "https://github.com/qv1ko/racingtracker/tree/main/app/Http/Requests"
    click Models "https://github.com/qv1ko/racingtracker/tree/main/app/Models"
    click InertiaMiddleware "https://github.com/qv1ko/racingtracker/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
    click DBConfig "https://github.com/qv1ko/racingtracker/blob/main/config/database.php"
    click MailAPI "https://github.com/qv1ko/racingtracker/blob/main/config/mail.php"
    click ConfigInertia "https://github.com/qv1ko/racingtracker/blob/main/config/inertia.php"
    click FileStorage "https://github.com/qv1ko/racingtracker/tree/main/storage/"
    click Migrations "https://github.com/qv1ko/racingtracker/tree/main/database/migrations"
    click Seeders "https://github.com/qv1ko/racingtracker/tree/main/database/seeders"
    click Seeders "https://github.com/qv1ko/racingtracker/tree/main/database/factories"
    click Lint "https://github.com/qv1ko/racingtracker/blob/main/.github/workflows/lint.yml"
    click Tests "https://github.com/qv1ko/racingtracker/blob/main/.github/workflows/tests.yml"
    click Repo "https://github.com/qv1ko/racingtracker/blob/main/.env.example"
    click Tests "https://github.com/qv1ko/racingtracker/blob/main/phpunit.xml"
    click Tests "https://github.com/qv1ko/racingtracker/tree/main/tests/"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#099,stroke-width:1px
    classDef backend fill:#e0f0ff,stroke:#036,stroke-width:1px
    classDef database fill:#ffecd0,stroke:#d60,stroke-width:1px
    classDef storage fill:#dddddd,stroke:#888,stroke-width:1px
    classDef external stroke-dasharray: 5 5,stroke:#999,fill:#fff
```
