# Architecture and data flow

## System overview

WeatherTool is a Scala backend, SolidJS frontend, and PostgreSQL database used to inspect Latvian weather observations and prepare map-based newsroom graphics.

```text
External providers                    Local/staging workflow
LVGMC station FTP/CSV ----+           Synthetic SQL seed
LVGMC forecast CSV -------+                    |
DMI HARMONIE APIs --------+                    v
                          v              PostgreSQL
                    Scala ingestion          |
                          |                   |
                          +---------> Scala/http4s API
                                             |
                                             v
                                      SolidJS web UI
                                             |
                                             v
                                 Canvas preview and PNG export
```

Staging currently exercises the PostgreSQL → API → frontend path with synthetic observations. It does not emulate LVGMC forecast files or HARMONIE GRIB files.

## Components

### Scala backend

- Serves JSON API routes and the built frontend from `web/dist`.
- Queries and aggregates station observations in PostgreSQL.
- Contains ingestion/parsing code for LVGMC station and forecast data.
- Contains HARMONIE discovery, download, GRIB parsing, and rendering support.
- Starts scheduled ingestion/cleanup tasks unless `ENABLE_SCHEDULED_JOBS=false`.

### SolidJS frontend

- Queries the backend using the same origin in production builds.
- Provides Stations, City Analysis, Faktiskā, Latvia overview, Database, HARMONIE, and LVGMC forecast workspaces.
- Uses HTML canvas for broadcast maps and PNG export.
- Uses the bundled `ltv_meteo.otf` font for weather symbols; the glyphs are font characters, not emoji.

### PostgreSQL

- Stores normalized weather observations used by Stations, City Analysis, Faktiskā, and Latvia overview.
- Is accessible only inside the isolated Compose network in staging.
- Uses a bind-mounted `postgres/` runtime directory in the current Compose configuration.

## Main observation-data flow

1. An ingestion job parses provider station data, or the development seed inserts synthetic rows.
2. Observations are stored in the `weather` table.
3. The frontend requests an API route containing cities, time range, granularity, field, and aggregate key.
4. The backend performs the database query and returns JSON.
5. The frontend renders cards, lists, charts, or canvas graphics.
6. Broadcast maps can be downloaded as PNG files entirely in the browser.

## Broadcast-map flow

### City Analysis temperature maps

Queried city values are placed at predefined coordinates on one of four map backgrounds:

- `map_1920x1080`
- `map_1920x1080_wind`
- `map_3840x1440`
- `map_3840x1440_wind`

The operator can add title/source overlays and export the rendered canvas.

### Faktiskā

Faktiskā queries temperature values, then lets the operator assign bundled weather-font glyphs to selected cities. One symbol can be applied to all cities and exceptions adjusted individually. Temperature badges, symbols, title, and source are composed into the downloaded PNG.

## What the repository does not provide by itself

- Authorized provider accounts and credentials.
- Workplace deployment topology or authentication requirements.
- Real LVGMC forecast CSV fixtures for development.
- Real HARMONIE GRIB fixtures for development.
- A complete automated test suite.
- Production monitoring, backups, incident handling, or a reviewed security boundary.

See `UPDATE_ROADMAP.md` before considering workplace deployment.