f1 intelligence
./docs / architecture

Architecture

Monorepo Layout

f1-intelligence/
├── apps/
│   ├── web/       Astro SSR frontend: Cloudflare Pages
│   ├── api/       Hono REST API: Cloudflare Workers
│   └── e2e/       Playwright smoke tests against a fixture API
└── data-engine/   Python ETL worker: Render

The schema source of truth lives in apps/api/src/db/schema/. Generated SQL migration files live in apps/api/drizzle/migrations/: both are owned by apps/api/, not a separate top-level package.


How the Four Layers Connect

┌─────────────────────────────────────────────────┐
│  Browser                                        │
└────────────────────┬────────────────────────────┘
                     │ HTTPS
┌────────────────────▼────────────────────────────┐
│  apps/web/  (Astro SSR: Cloudflare Pages)      │
│  Renders HTML server-side, fetches from API     │
│  in Astro frontmatter (never client-side JS)    │
└────────────────────┬────────────────────────────┘
                     │ HTTP (PUBLIC_API_URL)
┌────────────────────▼────────────────────────────┐
│  apps/api/  (Hono: Cloudflare Workers)         │
│  Read-only REST API, Drizzle ORM queries        │
│  Uses @neondatabase/serverless (HTTP driver)    │
│  Edge cache (Cloudflare Cache API)              │
└────────────────────┬────────────────────────────┘
                     │ Neon HTTP
┌────────────────────▼────────────────────────────┐
│  Neon PostgreSQL                                │
│  Shared DB: written by data-engine,            │
│  read by api                                    │
└────────────────────▲────────────────────────────┘
                     │ psycopg2 TCP
┌────────────────────┴────────────────────────────┐
│  data-engine/  (Python: Render Web Service)    │
│  Fetches F1 data via OpenF1 + Jolpica, computes │
│  features and predictions, writes to DB         │
└─────────────────────────────────────────────────┘

Key Constraints

Cloudflare Workers have no TCP. The apps/api/ layer must use @neondatabase/serverless (HTTP driver). Never use pg or postgres packages there.

Python writes directly to Neon. The API is read-only. There are no write endpoints: the ETL engine connects directly via psycopg2. Fresh data reaches the site once the edge caches lapse: 10 min inside a write window; between windows the data can’t change, so pages hold until the next window or 00:00 UTC.

All data fetching in Astro frontmatter. No client-side data fetching, no React/Vue islands for data. The --- blocks handle everything server-side. The only exceptions are GlobalSearch, DriverCompareTool and TeamCompareTool, whose data depends on arbitrary user input (see Frontend).

Stay inside the free tiers. Neon Free, Render Free and Cloudflare’s free plan; local dev and tests never touch Neon. Rules and numbers: docs/plans/intelligence-platform-roadmap.md §1–§2.


Data Flow: Conventional Weekend

Saturday
  data-engine: ingest_qualifying   → qualifying_results table
  data-engine: ingest_fp2          → fp2_long_run_times table
  data-engine: compute_features    → driver_prediction_features + race_predictions (one transaction)
  data-engine: compute_title_odds  → title_odds_drivers + title_odds_teams (optional step)
  data-engine: ingest_qualifying_telemetry → qualifying_lap_telemetry (optional step)
  race.status: scheduled → qualifying_done

Sunday
  data-engine: ingest_race         → race_results + lap_times tables
  data-engine: compute_season_stats→ driver_season_stats + team_season_stats
  data-engine: compute_title_odds  → title_odds_drivers + title_odds_teams
  data-engine: race events (optional, once past OpenF1's live window)
               ingest_race_control / ingest_overtakes / ingest_team_radio / ingest_stints / ingest_pit_stops
  race.status: qualifying_done → completed

Data Flow: Sprint Weekend

Friday
  data-engine: ingest_sprint_qualifying → sprint_results (SQ grid + sq1/sq2/sq3 times)
  data-engine: compute_sprint_features  → driver_sprint_features + sprint_predictions
  race.status: scheduled → sprint_qualifying_done

Saturday
  data-engine: ingest_sprint        → sprint_results (finish positions), sprint_lap_times,
                                      races (sprint_weather, sprint_safety_car_laps, etc.)
  data-engine: compute_season_stats → updates sprint aggregates in driver_season_stats
  race.status: sprint_qualifying_done → sprint_done

  data-engine: ingest_qualifying    → qualifying_results
  data-engine: ingest_fp2           → fp2_long_run_times
  data-engine: compute_features     → driver_prediction_features + race_predictions
  race.status: sprint_done → qualifying_done

Sunday
  data-engine: ingest_race          → race_results + lap_times
  data-engine: compute_season_stats → final season stats
  race.status: qualifying_done → completed

Screenshots

Home

Home page

Races calendar

Races page

Race detail

Race detail page

Race story: gap to leader and positions, lap by lap

Race story page

Qualifying telemetry: two fastest laps compared

Telemetry page

Driver standings

Drivers page

Driver detail

Driver detail page

Constructors: pit crew rankings

Teams page

Constructor detail

Team detail page

Circuits directory

Circuits page

Circuit detail

Circuit detail page

Driver comparison tool

Driver comparison page

Team comparison tool

Team comparison page

All-time history (F1DB)

History page


Deployment

LayerHostTrigger
apps/web/Cloudflare PagesPush to master → GitHub integration auto-deploys
apps/api/Cloudflare WorkersPush to master → GitHub integration auto-deploys
data-engine/RenderWeb Service running one worker loop: every 20 min inside a race-weekend window, every 6 h outside it
DB migrationsNeonManual: bun run db:generate + bun run db:migrate from apps/api/