# formulafactorchampionship/formula-factor architecture

> Architecture diagram of the GitHub repository formulafactorchampionship/formula-factor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/formulafactorchampionship/formula-factor
- Repository: https://github.com/formulafactorchampionship/formula-factor

## Overview

FFC is a sim-racing championship web app with an admin panel and live timing. The main workflow is a visitor or administrator using the static SPA; administrators can use server APIs to review archived sessions and account audits, while race results are prepared as import drafts. Live timing is served through a Node server or a Cloud Run relay, with stored records also published for the static site. README documents the visual modules and deployment split; some SPA and server behavior is unsampled, so those links are limited to documented relationships.

Main entry points: [`server/server.js`](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/server.js) (Admin API), [`script.js`](https://github.com/formulafactorchampionship/formula-factor/blob/main/script.js) (Championship SPA), [`relay/server.js`](https://github.com/formulafactorchampionship/formula-factor/blob/main/relay/server.js) (Cloud Run Relay), [`server/race-results-import.js`](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/race-results-import.js) (Race Importer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Championship Web"]
  node_spa["Championship SPA<br/>[script.js]"]
  node_page["Page Shell<br/>[index.html]"]
end

subgraph group_admin["Administration"]
  node_admin_api["Admin API<br/>[server.js]"]
  node_env["Environment Loader<br/>[envLoader.js]"]
  node_account_audit["Account Audit"]
  node_race_import["Race Importer"]
  node_firestore_rules["Firestore Rules<br/>[firestore.rules]"]
  node_race_bundle["Race Import Bundle<br/>[race_import.json]"]
end

subgraph group_timing["Live Timing"]
  node_timing_store[("Timing Store")]
  node_upstream["Game Timing Feed"]
  node_relay["Cloud Run Relay<br/>[server.js]"]
  node_published_records["Published Records"]
end

subgraph group_visuals["Visual Effects"]
  node_effects["WebGL Effects"]
end

node_visitor(("Visitor / Admin"))
node_firebase[("Firebase / Firestore")]

node_visitor -->|"uses"| node_spa
node_page -->|"hosts"| node_spa
node_spa -->|"loads lazily"| node_effects
node_spa -->|"uses admin API"| node_admin_api
node_admin_api -->|"loads first"| node_env
node_admin_api -->|"calls audit"| node_account_audit
node_admin_api -->|"requests drafts"| node_race_import
node_admin_api -->|"uses records"| node_timing_store
node_admin_api -->|"uses feed"| node_upstream
node_account_audit -->|"reads / deletes"| node_firebase
node_firestore_rules -->|"secures"| node_firebase
node_race_import -->|"uses helpers"| node_timing_store
node_relay -->|"serves records"| node_timing_store
node_relay -->|"relays feed"| node_upstream
node_relay -->|"serves archived imports"| node_race_import
node_relay -->|"streams SSE"| node_spa
node_timing_store -.->|"publishes records"| node_published_records
node_race_import -.->|"publishes drafts"| node_race_bundle

click node_spa "https://github.com/formulafactorchampionship/formula-factor/blob/main/script.js"
click node_page "https://github.com/formulafactorchampionship/formula-factor/blob/main/index.html"
click node_admin_api "https://github.com/formulafactorchampionship/formula-factor/blob/main/server/server.js"
click node_env "https://github.com/formulafactorchampionship/formula-factor/blob/main/server/envLoader.js"
click node_account_audit "https://github.com/formulafactorchampionship/formula-factor/blob/main/server/emailAuditService.js"
click node_race_import "https://github.com/formulafactorchampionship/formula-factor/blob/main/server/race-results-import.js"
click node_firestore_rules "https://github.com/formulafactorchampionship/formula-factor/blob/main/firestore.rules"
click node_timing_store "https://github.com/formulafactorchampionship/formula-factor/blob/main/live-timing-store.js"
click node_upstream "https://github.com/formulafactorchampionship/formula-factor/blob/main/live-timing-upstream.js"
click node_relay "https://github.com/formulafactorchampionship/formula-factor/blob/main/relay/server.js"
click node_published_records "https://github.com/formulafactorchampionship/formula-factor/blob/main/live_timing_records.json"
click node_race_bundle "https://github.com/formulafactorchampionship/formula-factor/blob/main/race_import.json"
click node_effects "https://github.com/formulafactorchampionship/formula-factor/tree/main/components"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_page toneBlue
class node_admin_api,node_env,node_account_audit,node_race_import,node_firestore_rules,node_race_bundle,node_firebase toneAmber
class node_timing_store,node_upstream,node_relay,node_published_records toneMint
class node_effects toneRose
class node_visitor toneIndigo
```

## Components

### Championship Web

- [Championship SPA](https://github.com/formulafactorchampionship/formula-factor/blob/main/script.js): `script.js`
- [Page Shell](https://github.com/formulafactorchampionship/formula-factor/blob/main/index.html): `index.html`

### Administration

- [Admin API](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/server.js): `server/server.js`
- [Environment Loader](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/envLoader.js): `server/envLoader.js`
- [Account Audit](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/emailAuditService.js): `server/emailAuditService.js`
- [Race Importer](https://github.com/formulafactorchampionship/formula-factor/blob/main/server/race-results-import.js): `server/race-results-import.js`
- [Firestore Rules](https://github.com/formulafactorchampionship/formula-factor/blob/main/firestore.rules): `firestore.rules`
- [Race Import Bundle](https://github.com/formulafactorchampionship/formula-factor/blob/main/race_import.json): `race_import.json`

### Live Timing

- [Timing Store](https://github.com/formulafactorchampionship/formula-factor/blob/main/live-timing-store.js): `live-timing-store.js`
- [Game Timing Feed](https://github.com/formulafactorchampionship/formula-factor/blob/main/live-timing-upstream.js): `live-timing-upstream.js`
- [Cloud Run Relay](https://github.com/formulafactorchampionship/formula-factor/blob/main/relay/server.js): `relay/server.js`
- [Published Records](https://github.com/formulafactorchampionship/formula-factor/blob/main/live_timing_records.json): `live_timing_records.json`

### Visual Effects

- [WebGL Effects](https://github.com/formulafactorchampionship/formula-factor/tree/main/components): `components`

### Other components

- **Visitor / Admin**
- **Firebase / Firestore**

## Connections

- Visitor / Admin → Championship SPA: uses (evidence: `README.md`)
- Page Shell → Championship SPA: hosts (evidence: `README.md`)
- Championship SPA → WebGL Effects: loads lazily (evidence: `README.md`)
- Championship SPA → Admin API: uses admin API (evidence: `README.md`)
- Admin API → Environment Loader: loads first (evidence: `server/server.js`)
- Admin API → Account Audit: calls audit (evidence: `server/server.js`)
- Admin API → Race Importer: requests drafts (evidence: `server/server.js`)
- Admin API → Timing Store: uses records (evidence: `server/server.js`)
- Admin API → Game Timing Feed: uses feed (evidence: `server/server.js`)
- Account Audit → Firebase / Firestore: reads / deletes (evidence: `server/emailAuditService.js`)
- Firestore Rules → Firebase / Firestore: secures (evidence: `README.md`)
- Race Importer → Timing Store: uses helpers (evidence: `server/race-results-import.js`)
- Cloud Run Relay → Timing Store: serves records (evidence: `relay/server.js`)
- Cloud Run Relay → Game Timing Feed: relays feed (evidence: `relay/server.js`)
- Cloud Run Relay → Race Importer: serves archived imports (evidence: `relay/server.js`)
- Cloud Run Relay → Championship SPA: streams SSE (evidence: `README.md`)
- Timing Store → Published Records: publishes records
- Race Importer → Race Import Bundle: publishes drafts