How jared-chan/f1ml works
Main components
• Client (Web Browser)
• Frontend/UI layer (Streamlit app in app.py + SessionState helper)
• Controller/Router (app.py orchestrates user input → data → model → output)
• Data Ingestion & Cache layer
– Ergast Developer API (external HTTP service)
– Local JSON cache (db/cache/*.json)
• Static Data Storage
– CSV files (db/*.csv: circuits, constructors, drivers, races, status)
– Pre-computed NumPy arrays (db/races_npy/…)
• Model Management & Inference
– PyTorch model files (db/models/model_split*.pth)
– fs_manifest.csv (model metadata)
• Business Logic / Prediction Engine
– Data preprocessing
– Feature assembly
– Model inference
– Randomness injection
• Presentation layer
– Interactive graph components
– Slider control for lap selection
• Deployment Environment
– Heroku dyno (Procfile, .slugignore)
– Runtime dependencies (requirements.txt, setup.sh)
• Development Artifacts
– Jupyter notebooks (notebooks/*.ipynb)
– images/ (screenshots used on site)
Relationships and data flow
1. Browser → HTTP(S) → Heroku/Streamlit server
2. UI invokes controller (app.py)
3. Controller checks local JSON cache
– if miss → HTTP GET → Ergast API → store JSON in db/cache
– if hit → load JSON from db/cache
4. Controller loads static CSV & NumPy data as needed
5. Controller invokes Prediction Engine
– loads model(s) from db/models
– preprocesses features, applies randomness
– runs PyTorch inference
6. Prediction results → UI components (graphs, tables) → Browser
7. Optional: Data scientists use notebooks to retrain models or explore data
Architectural patterns
• MVC-style separation:
– View: Streamlit frontend
– Controller: app.py
– Model: ML models + data sources
• Cache-aside pattern for external API calls
• Modular layering (UI, Controller, Data, Model)
Technologies & frameworks
– Python 3.x
– Streamlit (web UI)
– SessionState.py (Streamlit state management)
– PyTorch (.pth files)
– NumPy (race datasets)
– CSV (static reference data)
– Ergast Developer API (REST service)
– Heroku deployment (Procfile, setup.sh)
Don’t overthink—capture every discrete piece
Break the system into all logical subsystems:
– UI widgets (slider, graphs)
– Session state manager
– API fetcher + cache
– Static data loader
– Model loader
– Inference pipeline
– Deployment/Docker/Heroku