# sbalsara05/formula-function architecture

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

- Interactive diagram: https://gitdiagram.com/sbalsara05/formula-function
- Repository: https://github.com/sbalsara05/formula-function

## Overview

f(x) is a motorsport analytics product for F1, F2 and F3, combining a Next.js browsing experience with a FastAPI backend. The intended user journey spans driver profiles and career/telemetry analysis, team and venue exploration, and lap comparison; the backend also exposes standings and analytics endpoints. The sampled backend shows live standings backed by Jolpica and team data backed by Supabase, while several driver, lap and venue endpoints are placeholders. Frontend route-to-component and frontend-to-API wiring was not established by the excerpts, so those links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/sbalsara05/formula-function/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/components/driver/DriverPage.tsx`](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/DriverPage.tsx) (Driver profile), [`backend/app/routers/teams.py`](https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/teams.py) (Team endpoints), [`backend/app/services/jolpica.py`](https://github.com/sbalsara05/formula-function/blob/main/backend/app/services/jolpica.py) (Jolpica client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_series_page["Series hub<br/>[page.tsx]"]
  node_driver_route["Driver route<br/>[page.tsx]"]
  node_team_route["Team route<br/>[page.tsx]"]
  node_venue_route["Venue route<br/>[page.tsx]"]
  node_era_route["Era route<br/>[page.tsx]"]
  node_lap_routes["Lap routes<br/>[page.tsx]"]
  node_lap_detail_route["Lap detail route<br/>[page.tsx]"]
  node_lap_compare_route["Lap comparison route<br/>[page.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_driver_api["Driver endpoints<br/>[drivers.py]"]
  node_team_api["Team endpoints<br/>[teams.py]"]
  node_venue_api["Venue endpoints<br/>[venues.py]"]
  node_lap_api["Lap endpoints<br/>[laps.py]"]
  node_schemas["Domain schemas<br/>[schemas.py]"]
end

subgraph group_data["Persistence and feeds"]
  node_db_access["Supabase access<br/>[database.py]"]
  node_supabase[("Supabase store")]
  node_jolpica_service["Jolpica client<br/>[jolpica.py]"]
  node_jolpica["Jolpica API"]
end

subgraph group_analytics["Analytics views"]
  node_driver_page["Driver profile<br/>[DriverPage.tsx]"]
  node_cycling_reel["Career reel<br/>[CyclingReel.tsx]"]
  node_era_image["Era imagery<br/>[EraImage.tsx]"]
  node_radar_chart["Driving signature<br/>[RadarChart.tsx]"]
  node_trajectory["Career trajectory"]
  node_lap_analysis["Lap analysis"]
  node_lap_compare["Lap comparison"]
  node_team_page["Team profile<br/>[TeamPage.tsx]"]
  node_venue_page["Venue profile<br/>[VenuePage.tsx]"]
  node_track_map["Circuit map<br/>[TrackMap.tsx]"]
  node_era_page["Era feature<br/>[F1EraPage.tsx]"]
end

node_visitor(("Motorsport fan"))

node_visitor -.->|"browses"| node_series_page
node_driver_page -->|"renders"| node_cycling_reel
node_driver_page -->|"renders"| node_era_image
node_driver_page -->|"renders"| node_radar_chart
node_driver_page -->|"renders"| node_trajectory
node_venue_page -->|"renders"| node_track_map
node_api_app -->|"registers"| node_driver_api
node_api_app -->|"registers"| node_team_api
node_api_app -->|"registers"| node_venue_api
node_api_app -->|"registers"| node_lap_api
node_api_app -->|"fetches standings"| node_jolpica_service
node_driver_api -->|"validates responses"| node_schemas
node_driver_api -->|"requests standings"| node_jolpica_service
node_team_api -->|"validates responses"| node_schemas
node_team_api -->|"requests standings"| node_jolpica_service
node_team_api -->|"queries"| node_db_access
node_venue_api -->|"validates responses"| node_schemas
node_lap_api -->|"validates responses"| node_schemas
node_db_access -->|"creates client"| node_supabase
node_jolpica_service -->|"requests data"| node_jolpica

click node_series_page "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/page.tsx"
click node_driver_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/page.tsx"
click node_team_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/team/%5Bslug%5D/page.tsx"
click node_venue_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/venue/%5Bslug%5D/page.tsx"
click node_era_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/era/%5Bslug%5D/page.tsx"
click node_lap_routes "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/laps/page.tsx"
click node_lap_detail_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/laps/%5BlapId%5D/page.tsx"
click node_lap_compare_route "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/compare/laps/%5BlapA%5D/%5BlapB%5D/page.tsx"
click node_driver_page "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/DriverPage.tsx"
click node_cycling_reel "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/CyclingReel.tsx"
click node_era_image "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/EraImage.tsx"
click node_radar_chart "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/RadarChart.tsx"
click node_trajectory "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/TrajectoryModule.tsx"
click node_lap_analysis "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/LapAnalysisPage.tsx"
click node_lap_compare "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/ComparePageClient.tsx"
click node_team_page "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/team/TeamPage.tsx"
click node_venue_page "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/venue/VenuePage.tsx"
click node_track_map "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/venue/TrackMap.tsx"
click node_era_page "https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/era/F1EraPage.tsx"
click node_api_app "https://github.com/sbalsara05/formula-function/blob/main/backend/app/main.py"
click node_driver_api "https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/drivers.py"
click node_team_api "https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/teams.py"
click node_venue_api "https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/venues.py"
click node_lap_api "https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/laps.py"
click node_schemas "https://github.com/sbalsara05/formula-function/blob/main/backend/app/models/schemas.py"
click node_db_access "https://github.com/sbalsara05/formula-function/blob/main/backend/app/database.py"
click node_jolpica_service "https://github.com/sbalsara05/formula-function/blob/main/backend/app/services/jolpica.py"

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_series_page,node_driver_route,node_team_route,node_venue_route,node_era_route,node_lap_routes,node_lap_detail_route,node_lap_compare_route toneBlue
class node_api_app,node_driver_api,node_team_api,node_venue_api,node_lap_api,node_schemas toneAmber
class node_db_access,node_supabase,node_jolpica_service,node_jolpica toneMint
class node_driver_page,node_cycling_reel,node_era_image,node_radar_chart,node_trajectory,node_lap_analysis,node_lap_compare,node_team_page,node_venue_page,node_track_map,node_era_page toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Series hub](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/page.tsx): `frontend/src/app/f/[series]/page.tsx`
- [Driver route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/page.tsx): `frontend/src/app/f/[series]/driver/[slug]/page.tsx`
- [Team route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/team/%5Bslug%5D/page.tsx): `frontend/src/app/f/[series]/team/[slug]/page.tsx`
- [Venue route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/venue/%5Bslug%5D/page.tsx): `frontend/src/app/f/[series]/venue/[slug]/page.tsx`
- [Era route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/era/%5Bslug%5D/page.tsx): `frontend/src/app/f/[series]/era/[slug]/page.tsx`
- [Lap routes](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/laps/page.tsx): `frontend/src/app/f/[series]/driver/[slug]/laps/page.tsx`
- [Lap detail route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/driver/%5Bslug%5D/laps/%5BlapId%5D/page.tsx): `frontend/src/app/f/[series]/driver/[slug]/laps/[lapId]/page.tsx`
- [Lap comparison route](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/app/f/%5Bseries%5D/compare/laps/%5BlapA%5D/%5BlapB%5D/page.tsx): `frontend/src/app/f/[series]/compare/laps/[lapA]/[lapB]/page.tsx`

### API and domain

- [FastAPI application](https://github.com/sbalsara05/formula-function/blob/main/backend/app/main.py): `backend/app/main.py`
- [Driver endpoints](https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/drivers.py): `backend/app/routers/drivers.py`
- [Team endpoints](https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/teams.py): `backend/app/routers/teams.py`
- [Venue endpoints](https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/venues.py): `backend/app/routers/venues.py`
- [Lap endpoints](https://github.com/sbalsara05/formula-function/blob/main/backend/app/routers/laps.py): `backend/app/routers/laps.py`
- [Domain schemas](https://github.com/sbalsara05/formula-function/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`

### Persistence and feeds

- [Supabase access](https://github.com/sbalsara05/formula-function/blob/main/backend/app/database.py): `backend/app/database.py`
- **Supabase store**
- [Jolpica client](https://github.com/sbalsara05/formula-function/blob/main/backend/app/services/jolpica.py): `backend/app/services/jolpica.py`
- **Jolpica API**

### Analytics views

- [Driver profile](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/DriverPage.tsx): `frontend/src/components/driver/DriverPage.tsx`
- [Career reel](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/CyclingReel.tsx): `frontend/src/components/driver/CyclingReel.tsx`
- [Era imagery](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/EraImage.tsx): `frontend/src/components/driver/EraImage.tsx`
- [Driving signature](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/RadarChart.tsx): `frontend/src/components/driver/RadarChart.tsx`
- [Career trajectory](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/TrajectoryModule.tsx): `frontend/src/components/driver/TrajectoryModule.tsx`
- [Lap analysis](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/LapAnalysisPage.tsx): `frontend/src/components/driver/LapAnalysisPage.tsx`
- [Lap comparison](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/driver/ComparePageClient.tsx): `frontend/src/components/driver/ComparePageClient.tsx`
- [Team profile](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/team/TeamPage.tsx): `frontend/src/components/team/TeamPage.tsx`
- [Venue profile](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/venue/VenuePage.tsx): `frontend/src/components/venue/VenuePage.tsx`
- [Circuit map](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/venue/TrackMap.tsx): `frontend/src/components/venue/TrackMap.tsx`
- [Era feature](https://github.com/sbalsara05/formula-function/blob/main/frontend/src/components/era/F1EraPage.tsx): `frontend/src/components/era/F1EraPage.tsx`

### Other components

- **Motorsport fan**

## Connections

- Motorsport fan → Series hub: browses
- Driver profile → Career reel: renders (evidence: `frontend/src/components/driver/DriverPage.tsx`)
- Driver profile → Era imagery: renders (evidence: `frontend/src/components/driver/DriverPage.tsx`)
- Driver profile → Driving signature: renders (evidence: `frontend/src/components/driver/DriverPage.tsx`)
- Driver profile → Career trajectory: renders (evidence: `frontend/src/components/driver/DriverPage.tsx`)
- Venue profile → Circuit map: renders (evidence: `frontend/src/components/venue/VenuePage.tsx`)
- FastAPI application → Driver endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Team endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Venue endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Lap endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Jolpica client: fetches standings (evidence: `backend/app/main.py`)
- Driver endpoints → Domain schemas: validates responses (evidence: `backend/app/routers/drivers.py`)
- Driver endpoints → Jolpica client: requests standings (evidence: `backend/app/routers/drivers.py`)
- Team endpoints → Domain schemas: validates responses (evidence: `backend/app/routers/teams.py`)
- Team endpoints → Jolpica client: requests standings (evidence: `backend/app/routers/teams.py`)
- Team endpoints → Supabase access: queries (evidence: `backend/app/routers/teams.py`)
- Venue endpoints → Domain schemas: validates responses (evidence: `backend/app/routers/venues.py`)
- Lap endpoints → Domain schemas: validates responses (evidence: `backend/app/routers/laps.py`)
- Supabase access → Supabase store: creates client (evidence: `backend/app/database.py`)
- Jolpica client → Jolpica API: requests data (evidence: `backend/app/services/jolpica.py`)
