Skip to content

FoehnCast Docs

FoehnCast ranks Swiss kiteboarding spots for one rider profile by combining live weather forecasts, engineered wind features, drive-time information, and a trained quality model. Use the repository README for the short summary. Use this site for setup help, product scope, runtime notes, and operator guidance.

This site keeps rider-facing demo surfaces, service APIs, operator dashboards, and public-safe rendered evidence separate on purpose. Grafana belongs to the operator layer here. It is not the primary product UI and the public docs do not depend on live private dashboard embeds.

Start Here

Need Read this
Run the project locally with the default evaluator workflow Getting Started
Understand what stays in package config versus runtime wiring Configuration and Contracts
Understand the Feature-Training-Inference split Architecture
See how the hosted path maps onto GCP Cloud Mapping
Understand the main code and folder layout Repository
Understand the rider scope and data inputs Use Case and Data

Operating Model

Mode Who runs it Purpose
Local stack Any reader or contributor Development, evaluation, and reproducible validation
Online stack The operator of a fork or a personal cloud setup Full hosted deployment of Airflow, MLflow, and the API
GitHub automation Repository maintainer or fork owner Image publishing, Terraform workflows, and docs publishing

Public images are convenience artifacts, not a shared hosting promise. If you want a running online environment, deploy it in infrastructure you control.

Surface Guide

Surface Primary audience Exposure Current examples
Rider-facing demo surfaces rider, reviewer, contributor public-safe when shown as screenshots or rendered outputs Streamlit demo, ranking examples, and the online-features demo page
Service APIs clients, smoke tests, support services service-only /health, /spots, /predict, /rank, /features/online, and /metrics
Operator dashboards and control planes maintainer or deployment operator internal-only by default Airflow, MLflow, Prometheus, and Grafana
Public-safe docs and evidence reviewer, course audience, fork reader public-safe docs pages, rendered evaluation markdown, summary JSON-derived charts, and screenshots

Use the rider demo or API examples to explain the product surface. Use rendered artifacts or screenshots to explain operations in public docs. Keep live operator dashboards private unless you are intentionally running your own environment.

System In One View

flowchart LR OME[Open-Meteo forecast] --> FEAT[Feature DAG] FEAT --> PAR[(Curated features)] PAR --> TRAIN[Training DAG] TRAIN --> MLF[(MLflow registry)] OME --> APP[FastAPI app] OSRM[OSRM drive times] --> APP MLF --> APP APP --> API[Predict and rank endpoints] PAR --> FEAST[(Feast serving layer)] FEAST --> APP

Current Status

Area Status Meaning
Feature pipeline Working The feature DAG ingests, engineers, validates, and stores curated weather features
Training pipeline Working The training DAG labels data, trains the model, evaluates it, and registers fresh versions in MLflow under the requested registry alias
Inference pipeline Working The app serves the model-backed API routes used for health, prediction, and ranking
Hosted runtime Working Terraform plus the online compose stack can run Airflow, MLflow, and the API on GCP
CI/CD Working GitHub Actions validates docs and infrastructure and supports remote Terraform operations

Documentation Map

Overview

  • Getting Started: choose the right setup path and run the first commands.
  • Use Case and Data: the rider profile, spot set, and data sources behind the ranking.
  • Repository: where the code, orchestration, tests, docs, and demo live.
  • Configuration and Contracts: what belongs in config.yaml, what runtime env resolves, and what infrastructure keeps outside the package.

Runtime and Deployment

  • Architecture: the stable Feature-Training-Inference split and runtime surfaces.
  • Local Evaluator: the default local runtime contract for contributors.
  • Hosted Full-Stack: the active shared hosted runtime target and sync contract.
  • Cloud Mapping: how local boundaries map onto hosted storage and runtime choices.

Pipelines and Modeling

  • Feature Pipeline: how data moves from forecast ingestion to curated features.
  • Training Pipeline: how labeled data becomes a registered serving model.
  • Inference Pipeline: how prediction, ranking, and online feature lookup are served.
  • Seasonality: how cyclical time features capture recurring daily and yearly structure.

Operations

  • Monitoring: how Prometheus, Grafana, alerts, and runtime evidence stay on the operator side.