# kkowalewski24/social-racetrack architecture

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

- Interactive diagram: https://gitdiagram.com/kkowalewski24/social-racetrack
- Repository: https://github.com/kkowalewski24/social-racetrack

## Overview

##### Project type and purpose
- This is a full-stack, single-page React application (“Social-Racetrack”) backed by Firebase (Authentication, Firestore, Storage, Cloud Functions, Hosting).
- Purpose: allow public users to browse racetracks and races, authenticated users to create/join races, and admins to manage racetracks, events, and user roles.

##### File structure
- Top level:
– src/            → React front-end components, pages, logic, configuration
– public/         → static HTML/manifest for hosting
– functions/      → Firebase Cloud Functions (TypeScript)
– .env, firebase.json, firestore.rules/indexes, storage.rules → Firebase configuration & rules
- src/ layers:
– component/      → reusable UI widgets (cards, tables, forms)
– page/           → route-level views (Home, Login, Events, Account, Admin)
– logic/          → client-side business logic, controllers (DB, Auth, Storage) & models
– config/         → constants & environment config
– main/           → app entry (App.js, Routes.js, global styling)
- functions/src/index.ts registers HTTP‐triggered functions (e.g., grantAdmin, grantStandardUser).
- Deployment scripts in package.json (yarn fb:*) for hosting, functions, rules.

##### README for additional insights
- Firebase is core backend: Auth (email/password), Firestore (three collections with refPaths), Storage, Cloud Functions.
- DatabaseController pattern: client controllers fetch full objects by resolving references.
- Cascade deletion via Cloud Functions and security rules.
- Hosting on Firebase Hosting, CI via yarn scripts.

##### Main components
a. Frontend (React SPA)
– Pages & Components
– AuthContextProvider for user session
– Controllers calling Firebase SDK
b. Firebase Authentication
c. Firestore Database
– Collections: Racetracks, Events, Members
– Security & Index Rules
d. Firebase Storage (for racetrack/member images)
e. Cloud Functions (TypeScript)
– grantAdmin, grantStandardUser, cascade delete logic
f. Firebase Hosting (serving the SPA)

##### Relationships and data flow
- Frontend ↔ Firebase Auth via SDK (login, signup, token management)
- Frontend ↔ Firestore (CRUD on collections) via DatabaseController classes
- Frontend ↔ Storage (upload images) via FirebaseStorageController
- Frontend ↔ Cloud Functions (e.g., grantAdmin) over HTTP calls
- Firestore Triggers or Function calls enforce cascade deletes and role checks
- Firebase Hosting serves static build of React app

##### Architectural patterns and design principles
- Single-page application (SPA) with React Router (Routes.js)
- Context API for global auth state
- Controller pattern abstracts Firebase SDK calls
- Separation of concerns: UI Components vs Pages vs Logic vs Config
- Modular Cloud Functions for backend operations
- Security by Firebase Rules (firestore.rules, storage.rules)

a. Start by placing the React client on the left. Inside it, outline:
– App.js / Routes.js
– AuthContextProvider
– Controllers (Database, Storage, CloudFunctions)
– UI Pages & reusable Components
b. On the right, place Firebase services horizontally or in a “cloud”:
– React.AuthContextProvider → Firebase Auth
– Controllers → Firestore / Storage
– grantAdmin calls → Cloud Functions
– Firestore Triggers → Cloud Functions
– Hosting serves React build → Users’ Browser
e. Key flow, e.g., user signup → Auth → new Member in Firestore → grantStandardUser function → customClaims.

##### Detail without over-complicating
- Firebase service as its own component
- Client-side layers (UI vs Logic vs Config)
- Deployment scripts and .env config as a footnote, if desired

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client (React SPA)"
        direction TB
        App["App.js / Routes.js"]:::frontend
        AuthCtx["AuthContextProvider"]:::frontend
        CFClient["CloudFunctions.js"]:::frontend
        DBController["DatabaseController"]:::frontend
        RacetrackCtrl["RacetrackDatabaseController"]:::frontend
        EventCtrl["EventDatabaseController"]:::frontend
        MemberCtrl["MemberDatabaseController"]:::frontend
        StorageCtrl["FirebaseStorageController"]:::frontend
        RacetrackStorage["RacetrackFirebaseStorageController"]:::frontend
        Components["UI Components"]:::frontend
        Pages["Route-Level Pages"]:::frontend
        Config["firebase-constants.js"]:::frontend
    end

    %% Firebase Backend
    subgraph "Firebase Backend"
        direction TB
        Auth["Authentication"]:::firebaseService
        Firestore["Firestore Database"]:::db
        Storage["Storage Bucket"]:::db
        Functions["Cloud Functions"]:::function
        Hosting["Firebase Hosting"]:::firebaseService
        FSRules(("firestore.rules / firestore.indexes.json")):::note
        SRules(("storage.rules")):::note
    end

    %% Connections
    App --> AuthCtx
    AuthCtx --> Auth
    App --> CFClient
    CFClient -.->|HTTP Calls| Functions
    App --> DBController
    DBController --> Firestore
    StorageCtrl --> Storage
    RacetrackStorage --> Storage
    App --> StorageCtrl
    App -->|uses| Components
    App -->|renders| Pages
    App --> Config
    RacetrackCtrl --> DBController
    EventCtrl --> DBController
    MemberCtrl --> DBController
    Firestore -.->|Trigger Cascade| Functions
    Hosting --> App
    Firestore --- FSRules
    Storage --- SRules

    %% Click Events
    click App "https://github.com/kkowalewski24/social-racetrack/blob/master/src/main/App.js"
    click App "https://github.com/kkowalewski24/social-racetrack/blob/master/src/main/Routes.js"
    click AuthCtx "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/AuthContextProvider.js"
    click CFClient "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/CloudFunctions.js"
    click DBController "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/DatabaseController.js"
    click RacetrackCtrl "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/model/RacetrackDatabaseController.js"
    click EventCtrl "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/model/EventDatabaseController.js"
    click MemberCtrl "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/model/MemberDatabaseController.js"
    click StorageCtrl "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/FirebaseStorageController.js"
    click RacetrackStorage "https://github.com/kkowalewski24/social-racetrack/blob/master/src/logic/controller/model/RacetrackFirebaseStorageController.js"
    click Components "https://github.com/kkowalewski24/social-racetrack/tree/master/src/component/"
    click Pages "https://github.com/kkowalewski24/social-racetrack/tree/master/src/page/"
    click Config "https://github.com/kkowalewski24/social-racetrack/blob/master/src/config/constant/firebase-constants.js"
    click FSRules "https://github.com/kkowalewski24/social-racetrack/blob/master/firestore.rules"
    click FSRules "https://github.com/kkowalewski24/social-racetrack/blob/master/firestore.indexes.json"
    click SRules "https://github.com/kkowalewski24/social-racetrack/blob/master/storage.rules"
    click Hosting "https://github.com/kkowalewski24/social-racetrack/blob/master/firebase.json"
    click Hosting "https://github.com/kkowalewski24/social-racetrack/blob/master/public/index.html"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef firebaseService fill:#ffd8b1,stroke:#d15807,color:#d15807,stroke-width:1px
    classDef db fill:#d4f4dd,stroke:#28a745,color:#28a745,stroke-width:1px
    classDef function fill:#f0e68c,stroke:#b5a42e,color:#b5a42e,stroke-width:1px
    classDef note fill:#eeeeee,stroke:#888888,color:#333333,stroke-width:1px,stroke-dasharray: 2 2
```
