# timothylee58/jalur-apexgp architecture

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

- Interactive diagram: https://gitdiagram.com/timothylee58/jalur-apexgp
- Repository: https://github.com/timothylee58/jalur-apexgp

## Overview

Jalur APEXGP is a public Sepang race-weekend strategy simulator with companion fan, data, and trip-planning features. The main workflow is selecting a session and scenario in the strategy UI, fetching blended weather, generating conservative and aggressive tyre/stint reads, then displaying confidence and pit windows; unmodified live reads are logged. The README also documents chat, picks, telemetry, standings, accuracy, and transit capabilities. Some of those implementations were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api/routes/predict.py`](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/predict.py) (Prediction route), [`backend/app/api/routes/telemetry.py`](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/telemetry.py) (Telemetry API), [`backend/app/services/rag_service.py`](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/rag_service.py) (Context retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_strategy_ui["Strategy experience"]
  node_predict_page["Strategy page<br/>[page.tsx]"]
  node_predict_client["Scenario controls<br/>[PredictClient.tsx]"]
  node_prediction_hook["Prediction hook<br/>[usePrediction.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_strategy_backend["Strategy services"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_predict_route["Prediction route<br/>[predict.py]"]
  node_weather["Weather blend<br/>[weather_service.py]"]
  node_simulator["Strategy simulator"]
  node_prediction_schema["Prediction models<br/>[prediction.py]"]
  node_mlflow["MLflow tracking<br/>[mlflow_client.py]"]
  node_accuracy["Read accuracy"]
end

subgraph group_race_data["Race data features"]
  node_jolpica["Schedule and standings<br/>[jolpica_service.py]"]
  node_telemetry["Telemetry views"]
  node_telemetry_route["Telemetry API<br/>[telemetry.py]"]
  node_telemetry_pipeline["Telemetry pipeline"]
end

subgraph group_fan_features["Fan experiences"]
  node_chat["Race engineer chat"]
  node_chat_route["Chat API<br/>[chat.py]"]
  node_rag["Context retrieval<br/>[rag_service.py]"]
  node_knowledge["Knowledge corpus<br/>[knowledge_base.py]"]
end

subgraph group_trip_features["Picks and access"]
  node_picks["Race picks<br/>[PicksClient.tsx]"]
  node_picks_route["Picks API<br/>[picks.py]"]
  node_transit["Transit access"]
  node_transit_route["Transit API<br/>[transit.py]"]
  node_transit_service["Live transit ETL<br/>[transit_service.py]"]
end

node_visitor(("Race fan"))
node_external_weather(("Open-Meteo"))
node_external_mlflow(("MLflow service"))
node_external_jolpica(("Jolpica API"))
node_external_transit(("Government GTFS"))

node_visitor -->|"opens"| node_predict_page
node_predict_page -.->|"renders"| node_predict_client
node_predict_client -.->|"requests reads"| node_prediction_hook
node_prediction_hook -.->|"calls API"| node_api_client
node_api_client -->|"calls backend"| node_api_app
node_api_app -->|"routes requests"| node_predict_route
node_predict_route -->|"gets snapshot"| node_weather
node_weather -->|"fetches forecast"| node_external_weather
node_predict_route -->|"builds prediction"| node_simulator
node_predict_route -->|"uses models"| node_prediction_schema
node_simulator -->|"returns model"| node_prediction_schema
node_predict_route -->|"logs live read"| node_mlflow
node_mlflow -->|"records runs"| node_external_mlflow
node_predict_route -->|"records snapshot"| node_accuracy
node_visitor -.->|"asks questions"| node_chat
node_chat -.->|"sends prompt"| node_chat_route
node_api_app -->|"routes requests"| node_chat_route
node_chat_route -->|"streams answers"| node_rag
node_rag -->|"retrieves context"| node_knowledge
node_rag -->|"loads live standings"| node_jolpica
node_visitor -.->|"explores telemetry"| node_telemetry
node_api_app -->|"routes requests"| node_telemetry_route
node_telemetry_route -->|"builds telemetry"| node_telemetry_pipeline
node_telemetry_route -.->|"serves telemetry"| node_telemetry
node_visitor -.->|"submits picks"| node_picks
node_api_app -->|"routes requests"| node_picks_route
node_picks -.->|"uses picks API"| node_picks_route
node_visitor -.->|"checks access"| node_transit
node_api_app -->|"routes requests"| node_transit_route
node_transit -.->|"requests ETL read"| node_transit_route
node_transit_route -->|"gets live access"| node_transit_service
node_transit_service -->|"reads GTFS feeds"| node_external_transit
node_jolpica -->|"fetches results"| node_external_jolpica

click node_predict_page "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/predict/page.tsx"
click node_predict_client "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/predict/PredictClient.tsx"
click node_prediction_hook "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/hooks/usePrediction.ts"
click node_api_client "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/lib/api.ts"
click node_api_app "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/main.py"
click node_predict_route "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/predict.py"
click node_weather "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/weather_service.py"
click node_simulator "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/strategy_service.py"
click node_prediction_schema "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/schemas/prediction.py"
click node_mlflow "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/core/mlflow_client.py"
click node_accuracy "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/accuracy_service.py"
click node_chat "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/chat/RaceEngineerChat.tsx"
click node_chat_route "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/chat.py"
click node_rag "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/rag_service.py"
click node_knowledge "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/knowledge_base.py"
click node_jolpica "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/jolpica_service.py"
click node_telemetry "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/telemetry/TelemetryDashboard.tsx"
click node_telemetry_route "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/telemetry.py"
click node_telemetry_pipeline "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/telemetry_pipeline.py"
click node_picks "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/picks/PicksClient.tsx"
click node_picks_route "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/picks.py"
click node_transit "https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/tickets/TransitAccessPanel.tsx"
click node_transit_route "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/transit.py"
click node_transit_service "https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/transit_service.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_predict_page,node_predict_client,node_prediction_hook,node_api_client toneBlue
class node_api_app,node_predict_route,node_weather,node_simulator,node_prediction_schema,node_mlflow,node_accuracy toneAmber
class node_jolpica,node_telemetry,node_telemetry_route,node_telemetry_pipeline,node_external_jolpica toneMint
class node_chat,node_chat_route,node_rag,node_knowledge toneRose
class node_picks,node_picks_route,node_transit,node_transit_route,node_transit_service,node_visitor,node_external_weather,node_external_mlflow,node_external_transit toneIndigo
```

## Components

### Strategy experience

- [Strategy page](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/predict/page.tsx): `frontend/app/predict/page.tsx`
- [Scenario controls](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/predict/PredictClient.tsx): `frontend/app/predict/PredictClient.tsx`
- [Prediction hook](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/hooks/usePrediction.ts): `frontend/hooks/usePrediction.ts`
- [API client](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Strategy services

- [FastAPI app](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/main.py): `backend/app/main.py`
- [Prediction route](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/predict.py): `backend/app/api/routes/predict.py`
- [Weather blend](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Strategy simulator](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/strategy_service.py): `backend/app/services/strategy_service.py`
- [Prediction models](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/schemas/prediction.py): `backend/app/schemas/prediction.py`
- [MLflow tracking](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/core/mlflow_client.py): `backend/app/core/mlflow_client.py`
- [Read accuracy](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/accuracy_service.py): `backend/app/services/accuracy_service.py`

### Race data features

- [Schedule and standings](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/jolpica_service.py): `backend/app/services/jolpica_service.py`
- [Telemetry views](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/telemetry/TelemetryDashboard.tsx): `frontend/components/telemetry/TelemetryDashboard.tsx`
- [Telemetry API](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/telemetry.py): `backend/app/api/routes/telemetry.py`
- [Telemetry pipeline](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/telemetry_pipeline.py): `backend/app/services/telemetry_pipeline.py`

### Fan experiences

- [Race engineer chat](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/chat/RaceEngineerChat.tsx): `frontend/components/chat/RaceEngineerChat.tsx`
- [Chat API](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Context retrieval](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Knowledge corpus](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/knowledge_base.py): `backend/app/services/knowledge_base.py`

### Picks and access

- [Race picks](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/app/picks/PicksClient.tsx): `frontend/app/picks/PicksClient.tsx`
- [Picks API](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/picks.py): `backend/app/api/routes/picks.py`
- [Transit access](https://github.com/timothylee58/jalur-apexgp/blob/main/frontend/components/tickets/TransitAccessPanel.tsx): `frontend/components/tickets/TransitAccessPanel.tsx`
- [Transit API](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/api/routes/transit.py): `backend/app/api/routes/transit.py`
- [Live transit ETL](https://github.com/timothylee58/jalur-apexgp/blob/main/backend/app/services/transit_service.py): `backend/app/services/transit_service.py`

### Other components

- **Race fan**
- **Open-Meteo**
- **MLflow service**
- **Jolpica API**
- **Government GTFS**

## Connections

- Race fan → Strategy page: opens (evidence: `README.md`)
- Strategy page → Scenario controls: renders
- Scenario controls → Prediction hook: requests reads
- Prediction hook → API client: calls API
- API client → FastAPI app: calls backend (evidence: `README.md`)
- FastAPI app → Prediction route: routes requests (evidence: `backend/app/main.py`)
- Prediction route → Weather blend: gets snapshot (evidence: `backend/app/api/routes/predict.py`)
- Weather blend → Open-Meteo: fetches forecast (evidence: `README.md`)
- Prediction route → Strategy simulator: builds prediction (evidence: `backend/app/api/routes/predict.py`)
- Prediction route → Prediction models: uses models (evidence: `backend/app/api/routes/predict.py`)
- Strategy simulator → Prediction models: returns model (evidence: `backend/app/schemas/prediction.py`)
- Prediction route → MLflow tracking: logs live read (evidence: `backend/app/api/routes/predict.py`)
- MLflow tracking → MLflow service: records runs (evidence: `README.md`)
- Prediction route → Read accuracy: records snapshot (evidence: `backend/app/api/routes/predict.py`)
- Race fan → Race engineer chat: asks questions
- Race engineer chat → Chat API: sends prompt
- FastAPI app → Chat API: routes requests (evidence: `backend/app/main.py`)
- Chat API → Context retrieval: streams answers (evidence: `backend/app/api/routes/chat.py`)
- Context retrieval → Knowledge corpus: retrieves context (evidence: `backend/app/services/rag_service.py`)
- Context retrieval → Schedule and standings: loads live standings (evidence: `backend/app/services/rag_service.py`)
- Race fan → Telemetry views: explores telemetry
- FastAPI app → Telemetry API: routes requests (evidence: `backend/app/main.py`)
- Telemetry API → Telemetry pipeline: builds telemetry (evidence: `backend/app/api/routes/telemetry.py`)
- Telemetry API → Telemetry views: serves telemetry
- Race fan → Race picks: submits picks
- FastAPI app → Picks API: routes requests (evidence: `backend/app/main.py`)
- Race picks → Picks API: uses picks API
- Race fan → Transit access: checks access
- FastAPI app → Transit API: routes requests (evidence: `backend/app/main.py`)
- Transit access → Transit API: requests ETL read
- Transit API → Live transit ETL: gets live access (evidence: `backend/app/api/routes/transit.py`)
- Live transit ETL → Government GTFS: reads GTFS feeds (evidence: `README.md`)
- Schedule and standings → Jolpica API: fetches results (evidence: `backend/app/services/jolpica_service.py`)
