How kkowalewski24/social-racetrack works
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