# kkritika123/solar-flare-forecast architecture

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

- Interactive diagram: https://gitdiagram.com/kkritika123/solar-flare-forecast
- Repository: https://github.com/kkritika123/solar-flare-forecast

## Overview

Solar Flare Forecast retrieves historical CCMC forecasts and LMSAL observations, normalizes forecasts, then evaluates forecast windows using TSS/HSS. It also offers direct HAPI and processed-archive queries and source comparison. The principal archive path runs through the public API and processing pipeline; evaluation is separately orchestrated by the API. Edges reflect shown calls, SOURCE INDEX references, or README statements; unsampled implementation details are omitted.

Main entry points: [`flare_scoreboard/scoring.py`](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/scoring.py) (Evaluation orchestration), [`flare_scoreboard/api.py`](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/api.py) (Public API), [`flare_scoreboard/pipeline.py`](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/pipeline.py) (Download pipeline), [`query_forecasts.py`](https://github.com/kkritika123/solar-flare-forecast/blob/main/query_forecasts.py) (Query command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Forecast ingestion"]
  node_public_api["Public API<br/>[api.py]"]
  node_config["Workflow config<br/>[config.py]"]
  node_model_discovery["Model discovery<br/>[crawl.py]"]
  node_http_client["Archive HTTP<br/>[http_client.py]"]
  node_pipeline["Download pipeline<br/>[pipeline.py]"]
  node_parsers["Forecast parsers<br/>[parsers.py]"]
  node_parse_core["Parse normalization<br/>[parse_core.py]"]
  node_csv_output["Yearly CSV output<br/>[csv_output.py]"]
  node_forecast_archive[("Processed forecasts")]
end

subgraph group_query["Forecast queries"]
  node_query_cli["Query command<br/>[query_forecasts.py]"]
  node_query_api["Query and compare<br/>[api.py]"]
  node_hapi_client["HAPI client<br/>[hapi.py]"]
  node_hapi_service["CCMC HAPI"]
  node_query_results["Query CSV results"]
end

subgraph group_observations["Observed events"]
  node_lmsal_fetch["LMSAL retrieval<br/>[lmsal.py]"]
  node_lmsal_service["LMSAL archive"]
  node_event_data[("Observed event data")]
end

subgraph group_evaluation["Evaluation"]
  node_score_orchestration["Evaluation orchestration<br/>[scoring.py]"]
  node_event_matching["Window matching and scores<br/>[evaluation.py]"]
  node_evaluation_results["Evaluation CSV results"]
  node_legacy_eval["Legacy evaluation script<br/>[model.py]"]
  node_legacy_helpers["Evaluation helpers"]
end

node_user(("Researcher"))

node_user -->|"requests download/evaluation"| node_public_api
node_public_api -->|"loads settings"| node_config
node_public_api -->|"discovers models"| node_model_discovery
node_public_api -->|"processes models"| node_pipeline
node_pipeline -->|"crawls files"| node_model_discovery
node_pipeline -->|"downloads files"| node_http_client
node_pipeline -->|"parses files"| node_parsers
node_parsers -->|"uses helpers"| node_parse_core
node_pipeline -->|"writes yearly rows"| node_csv_output
node_csv_output -->|"writes forecasts"| node_forecast_archive
node_user -->|"runs query"| node_query_cli
node_query_cli -->|"queries archive"| node_query_api
node_query_cli -->|"queries HAPI"| node_hapi_client
node_query_api -->|"requests predictions"| node_hapi_client
node_hapi_client -->|"requests data"| node_hapi_service
node_query_cli -->|"reads archive CSVs"| node_forecast_archive
node_query_cli -->|"saves query CSVs"| node_query_results
node_user -->|"requests event download"| node_lmsal_fetch
node_lmsal_fetch -->|"retrieves events"| node_lmsal_service
node_lmsal_fetch -->|"writes event CSV"| node_event_data
node_public_api -->|"runs evaluation"| node_score_orchestration
node_score_orchestration -->|"calculates scores"| node_event_matching
node_score_orchestration -->|"reads forecasts"| node_forecast_archive
node_score_orchestration -->|"reads observations"| node_event_data
node_score_orchestration -->|"downloads if missing"| node_lmsal_fetch
node_score_orchestration -->|"writes scores"| node_evaluation_results
node_user -->|"runs legacy workflow"| node_legacy_eval
node_legacy_eval -->|"uses helpers"| node_legacy_helpers

click node_public_api "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/api.py"
click node_config "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/config.py"
click node_model_discovery "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/crawl.py"
click node_http_client "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/http_client.py"
click node_pipeline "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/pipeline.py"
click node_parsers "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/parsers.py"
click node_parse_core "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/parse_core.py"
click node_csv_output "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/csv_output.py"
click node_query_cli "https://github.com/kkritika123/solar-flare-forecast/blob/main/query_forecasts.py"
click node_query_api "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/api.py"
click node_hapi_client "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/hapi.py"
click node_query_results "https://github.com/kkritika123/solar-flare-forecast/tree/main/data"
click node_lmsal_fetch "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/lmsal.py"
click node_event_data "https://github.com/kkritika123/solar-flare-forecast/tree/main/data"
click node_score_orchestration "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/scoring.py"
click node_event_matching "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/evaluation.py"
click node_legacy_eval "https://github.com/kkritika123/solar-flare-forecast/blob/main/model.py"
click node_legacy_helpers "https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_eval_utils.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_public_api,node_config,node_model_discovery,node_http_client,node_pipeline,node_parsers,node_parse_core,node_csv_output,node_forecast_archive toneBlue
class node_query_cli,node_query_api,node_hapi_client,node_hapi_service,node_query_results toneAmber
class node_lmsal_fetch,node_lmsal_service,node_event_data toneMint
class node_score_orchestration,node_event_matching,node_evaluation_results,node_legacy_eval,node_legacy_helpers toneRose
class node_user toneIndigo
```

## Components

### Forecast ingestion

- [Public API](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/api.py): `flare_scoreboard/api.py`
- [Workflow config](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/config.py): `flare_scoreboard/config.py`
- [Model discovery](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/crawl.py): `flare_scoreboard/crawl.py`
- [Archive HTTP](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/http_client.py): `flare_scoreboard/http_client.py`
- [Download pipeline](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/pipeline.py): `flare_scoreboard/pipeline.py`
- [Forecast parsers](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/parsers.py): `flare_scoreboard/parsers.py`
- [Parse normalization](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/parse_core.py): `flare_scoreboard/parse_core.py`
- [Yearly CSV output](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/csv_output.py): `flare_scoreboard/csv_output.py`
- **Processed forecasts**

### Forecast queries

- [Query command](https://github.com/kkritika123/solar-flare-forecast/blob/main/query_forecasts.py): `query_forecasts.py`
- [Query and compare](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/api.py): `flare_scoreboard/api.py`
- [HAPI client](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/hapi.py): `flare_scoreboard/hapi.py`
- **CCMC HAPI**
- [Query CSV results](https://github.com/kkritika123/solar-flare-forecast/tree/main/data): `data`

### Observed events

- [LMSAL retrieval](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/lmsal.py): `flare_scoreboard/lmsal.py`
- **LMSAL archive**
- [Observed event data](https://github.com/kkritika123/solar-flare-forecast/tree/main/data): `data`

### Evaluation

- [Evaluation orchestration](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/scoring.py): `flare_scoreboard/scoring.py`
- [Window matching and scores](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_scoreboard/evaluation.py): `flare_scoreboard/evaluation.py`
- **Evaluation CSV results**
- [Legacy evaluation script](https://github.com/kkritika123/solar-flare-forecast/blob/main/model.py): `model.py`
- [Evaluation helpers](https://github.com/kkritika123/solar-flare-forecast/blob/main/flare_eval_utils.py): `flare_eval_utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Public API: requests download/evaluation (evidence: `README.md`)
- Public API → Workflow config: loads settings (evidence: `flare_scoreboard/api.py`)
- Public API → Model discovery: discovers models (evidence: `flare_scoreboard/api.py`)
- Public API → Download pipeline: processes models (evidence: `flare_scoreboard/api.py`)
- Download pipeline → Model discovery: crawls files (evidence: `flare_scoreboard/pipeline.py`)
- Download pipeline → Archive HTTP: downloads files (evidence: `flare_scoreboard/pipeline.py`)
- Download pipeline → Forecast parsers: parses files (evidence: `flare_scoreboard/pipeline.py`)
- Forecast parsers → Parse normalization: uses helpers (evidence: `flare_scoreboard/parsers.py`)
- Download pipeline → Yearly CSV output: writes yearly rows (evidence: `flare_scoreboard/pipeline.py`)
- Yearly CSV output → Processed forecasts: writes forecasts (evidence: `README.md`)
- Researcher → Query command: runs query (evidence: `README.md`)
- Query command → Query and compare: queries archive (evidence: `query_forecasts.py`)
- Query command → HAPI client: queries HAPI (evidence: `query_forecasts.py`)
- Query and compare → HAPI client: requests predictions (evidence: `flare_scoreboard/api.py`)
- HAPI client → CCMC HAPI: requests data (evidence: `flare_scoreboard/hapi.py`)
- Query command → Processed forecasts: reads archive CSVs (evidence: `README.md`)
- Query command → Query CSV results: saves query CSVs (evidence: `README.md`)
- Researcher → LMSAL retrieval: requests event download (evidence: `README.md`)
- LMSAL retrieval → LMSAL archive: retrieves events (evidence: `README.md`)
- LMSAL retrieval → Observed event data: writes event CSV (evidence: `README.md`)
- Public API → Evaluation orchestration: runs evaluation (evidence: `flare_scoreboard/api.py`)
- Evaluation orchestration → Window matching and scores: calculates scores (evidence: `flare_scoreboard/scoring.py`)
- Evaluation orchestration → Processed forecasts: reads forecasts (evidence: `README.md`)
- Evaluation orchestration → Observed event data: reads observations (evidence: `README.md`)
- Evaluation orchestration → LMSAL retrieval: downloads if missing (evidence: `README.md`)
- Evaluation orchestration → Evaluation CSV results: writes scores (evidence: `README.md`)
- Researcher → Legacy evaluation script: runs legacy workflow (evidence: `README.md`)
- Legacy evaluation script → Evaluation helpers: uses helpers (evidence: `model.py`)
