# aakarsh-88/f1-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/aakarsh-88/f1-analytics
- Repository: https://github.com/aakarsh-88/f1-analytics

## Overview

F1 Analytics is a historical Formula 1 dashboard: users explore overview statistics, driver and constructor careers, race details, championship standings, and cross-season analytics. The documented runtime path is Next.js pages and visualizations consuming a versioned FastAPI API backed by PostgreSQL. Backend routes delegate to domain services and repositories; repositories query the relational data. The README also documents search and Clerk authentication. Some frontend and backend feature files were not sampled, so their internal calls are represented only where the README or source index supports them.

Main entry points: [`frontend/src/app/(dashboard)`](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/app/(dashboard)) (Dashboard pages), [`backend/app/api/v1`](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/api/v1) (Feature routes), [`backend/app/repositories`](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/repositories) (Feature repositories), [`frontend/src/lib/api`](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/lib/api) (API clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webpages["Dashboard pages"]
  node_visuals["Feature visualizations"]
  node_webapi["API clients"]
  node_auth["Clerk authentication"]
end

subgraph group_api["REST API"]
  node_entry["Application entry<br/>[main.py]"]
  node_v1router["Versioned router<br/>[router.py]"]
  node_resource_routes["Feature routes"]
  node_dependencies["Request dependencies<br/>[deps.py]"]
  node_search["Cross-domain search"]
end

subgraph group_domain["Domain and queries"]
  node_feature_services["Feature services"]
  node_feature_repositories["Feature repositories"]
  node_models["F1 data models"]
  node_schemas["API schemas"]
  node_pagination["Pagination utilities<br/>[pagination.py]"]
end

subgraph group_storage["Persistence"]
  node_database_sessions["Database sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
end

node_visitor(("Dashboard user"))
node_data_import["CSV provisioning"]

node_visitor -->|"explores"| node_webpages
node_webpages -.->|"renders"| node_visuals
node_webpages -.->|"requests data"| node_webapi
node_webpages -.->|"authenticates"| node_auth
node_webapi -->|"calls REST API"| node_entry
node_entry -->|"mounts routes"| node_v1router
node_v1router -->|"registers"| node_resource_routes
node_resource_routes -->|"delegates"| node_feature_services
node_feature_services -->|"queries through"| node_feature_repositories
node_feature_repositories -->|"queries"| node_models
node_feature_repositories -.->|"uses sessions"| node_database_sessions
node_database_sessions -->|"connects"| node_postgres
node_resource_routes -->|"validates responses"| node_schemas
node_resource_routes -->|"uses pagination"| node_pagination
node_visitor -->|"searches"| node_search
node_data_import -->|"provisions data"| node_postgres

click node_webpages "https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/app/(dashboard)"
click node_visuals "https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/components"
click node_webapi "https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/lib/api"
click node_auth "https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/lib/auth"
click node_entry "https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/main.py"
click node_v1router "https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/api/v1/router.py"
click node_resource_routes "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/api/v1"
click node_dependencies "https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/api/deps.py"
click node_feature_services "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/services"
click node_feature_repositories "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/repositories"
click node_models "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/models"
click node_schemas "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/schemas"
click node_pagination "https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/utils/pagination.py"
click node_database_sessions "https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/core/database.py"
click node_search "https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/api/v1"
click node_data_import "https://github.com/aakarsh-88/f1-analytics/tree/main/scripts"

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_webpages,node_visuals,node_webapi,node_auth,node_visitor toneBlue
class node_entry,node_v1router,node_resource_routes,node_dependencies,node_search toneAmber
class node_feature_services,node_feature_repositories,node_models,node_schemas,node_pagination toneMint
class node_database_sessions,node_postgres toneRose
class node_data_import toneTeal
```

## Components

### Web experience

- [Dashboard pages](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [Feature visualizations](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/components): `frontend/src/components`
- [API clients](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/lib/api): `frontend/src/lib/api`
- [Clerk authentication](https://github.com/aakarsh-88/f1-analytics/tree/main/frontend/src/lib/auth): `frontend/src/lib/auth`

### REST API

- [Application entry](https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned router](https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Feature routes](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/api/v1): `backend/app/api/v1`
- [Request dependencies](https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Cross-domain search](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/api/v1): `backend/app/api/v1`

### Domain and queries

- [Feature services](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/services): `backend/app/services`
- [Feature repositories](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/repositories): `backend/app/repositories`
- [F1 data models](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/models): `backend/app/models`
- [API schemas](https://github.com/aakarsh-88/f1-analytics/tree/main/backend/app/schemas): `backend/app/schemas`
- [Pagination utilities](https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/utils/pagination.py): `backend/app/utils/pagination.py`

### Persistence

- [Database sessions](https://github.com/aakarsh-88/f1-analytics/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **PostgreSQL**

### Other components

- **Dashboard user**
- [CSV provisioning](https://github.com/aakarsh-88/f1-analytics/tree/main/scripts): `scripts`

## Connections

- Dashboard user → Dashboard pages: explores
- Dashboard pages → Feature visualizations: renders
- Dashboard pages → API clients: requests data
- Dashboard pages → Clerk authentication: authenticates
- API clients → Application entry: calls REST API
- Application entry → Versioned router: mounts routes (evidence: `backend/app/main.py`)
- Versioned router → Feature routes: registers (evidence: `backend/app/api/v1/router.py`)
- Feature routes → Feature services: delegates (evidence: `backend/app/api/v1/analytics.py`)
- Feature services → Feature repositories: queries through (evidence: `backend/app/services/standings_service.py`)
- Feature repositories → F1 data models: queries (evidence: `backend/app/repositories/standings_repository.py`)
- Feature repositories → Database sessions: uses sessions
- Database sessions → PostgreSQL: connects
- Feature routes → API schemas: validates responses (evidence: `backend/app/api/v1/analytics.py`)
- Feature routes → Pagination utilities: uses pagination (evidence: `backend/app/api/v1/constructors.py`)
- Dashboard user → Cross-domain search: searches
- CSV provisioning → PostgreSQL: provisions data
