86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
|
# 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.
|
||
|
|
|