From 4d2fadf0a95ead7edbf1726035e4b16e451f5572 Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Sun, 19 Jul 2026 11:42:26 +0200 Subject: [PATCH] update documentations for AI --- ARCHITECTURE.md | 21 ++++++++++++--------- mslib/msui/CLAUDE.md | 1 + mslib/utils/CLAUDE.md | 12 +++++------- 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a2ac2737e..ffbd53d38 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -10,13 +10,13 @@ are machine-enforced by import-linter (`pixi run -e dev lint-imports`, config in Arrows mean "may import". Anything not drawn is forbidden. ``` - ┌────────────┐ - │ mslib.msui │ PyQt5 desktop client (GUI) - └─────┬──────┘ + mslib.autoplot ──┐┌────────────┐ + (headless batch ▼│ mslib.msui │ PyQt5 desktop client (GUI) + plotting CLI) └─────┬──────┘ ┌──────────────┼───────────────────────┐ ▼ ▼ ▼ mslib.mscolab mslib.support mslib.utils - (events/message_ (vendored qt_json_view) (shared: config, + (events/message_ (vendored qt_json_view) (shared: config, constants, type constants coordinates, units, ONLY) netCDF, auth, qt helpers) ▲ @@ -30,9 +30,10 @@ Arrows mean "may import". Anything not drawn is forbidden. Grandfathered violations (do not add new ones; the lists live in `setup.cfg` under `ignore_imports` and must only shrink): -- `utils.{config,auth,airdata,migration.*}` import `msui.constants` (path constants). -- `utils.mssautoplot` drives the GUI plotting stack headlessly. - `plugins.io.{csv,text,flitestar}` import `msui.flighttrack`. +- the deprecation shim `utils/mssautoplot.py` re-exports `mslib.autoplot` + (delete the shim next release and the entry with it). A twin shim exists at + `msui/constants.py` → `utils/constants.py`. - `{mscolab,mswms}.blueprints.docs` import `msui.icons` — invisible to the linter (`blueprints/` are namespace packages without `__init__.py`), but equally discouraged. @@ -56,7 +57,7 @@ under `ignore_imports` and must only shrink): - `*_dockwidget.py` — airdata, autoplot, hexagon, kmloverlay, remotesensing, satellite, multiple_flightpath, multilayers dock widgets - `editor.py` — JSON config editor; `performance_settings.py`, `aircraft.py` -- `constants.py` — MSUI config paths (imported by utils — grandfathered) +- `constants.py` — deprecated shim; real module is `mslib/utils/constants.py` - `ui/` — Qt Designer sources; `qt5/` — pyuic5 output, NEVER edit by hand ### mslib/mscolab — collaboration server (Flask + SocketIO; entry: `mscolab`) @@ -81,18 +82,20 @@ under `ignore_imports` and must only shrink): - `demodata.py` / `seed.py` — demo data generation; `gallery_builder.py` — docs gallery - `app/`, `blueprints/` — Flask assembly; `mswms.py` — entry point -### mslib/utils — shared utilities (entry: `mssautoplot`) +### mslib/utils — shared utilities (the base layer) - `config.py` — `MSUIDefaultConfig` defaults + `config_loader` (THE config API) +- `constants.py` — MSUI config paths (moved here from msui in v11.1) - `coordinate.py`, `units.py`, `time.py`, `thermolib.py` — pure science helpers - `netCDF4tools.py` — NetCDF helpers; `ogcwms.py` — OWSLib WMS subclass - `auth.py` — keyring/password handling; `qt.py` — Qt helpers - `colordialog.py` — CustomColorDialog; `airdata.py` — airport/airspace download -- `mssautoplot.py` — headless batch plotting CLI (drives msui plotting stack) - `migration/` — config-format migrations between major versions ### Smaller packages +- `mslib/autoplot/` — `mssautoplot` CLI: headless batch plotting driving the + msui plotting stack (lives beside the GUI, not in the base layer) - `mslib/plugins/io/` — flight-track import/export formats (csv, kml, gpx, text, flitestar); registered via config `import_plugins`/`export_plugins` - `mslib/msidp/` — standalone SAML2 identity provider (entry: `msidp`) diff --git a/mslib/msui/CLAUDE.md b/mslib/msui/CLAUDE.md index f75d37c6c..9294e31f1 100644 --- a/mslib/msui/CLAUDE.md +++ b/mslib/msui/CLAUDE.md @@ -17,6 +17,7 @@ Global map: ../../ARCHITECTURE.md - `mscolab.py` + `socket_control.py` + `mscolab_*.py` — MSColab client; network events arrive as Qt signals emitted by `socket_control.ConnectionManager` - `*_dockwidget.py` — per-feature dock widgets +- `constants.py` — deprecated shim; import `mslib.utils.constants` instead - `ui/` — Qt Designer `.ui` sources; `qt5/` — pyuic5 OUTPUT, never edit ## May import diff --git a/mslib/utils/CLAUDE.md b/mslib/utils/CLAUDE.md index 7e48a0308..b46d36dfd 100644 --- a/mslib/utils/CLAUDE.md +++ b/mslib/utils/CLAUDE.md @@ -9,6 +9,7 @@ Global map: ../../ARCHITECTURE.md - `config.py` — `MSUIDefaultConfig` (all config keys as class attributes) + `config_loader(dataset=...)` (THE accessor) + JSON settings file IO + structural validation registries (`dict_option_structure` etc.) +- `constants.py` — MSUI config/cache paths (`MSUI_CONFIG_PATH`, `MSUI_SETTINGS`) - `coordinate.py`, `units.py`, `time.py`, `thermolib.py` — pure functions; the safest modules to edit; keep them dependency-free - `netCDF4tools.py` — NetCDF read helpers; `ogcwms.py` — hardened OWSLib WMS @@ -16,23 +17,20 @@ Global map: ../../ARCHITECTURE.md - `qt.py`, `colordialog.py` — Qt helpers (the only Qt code outside msui/support) - `airdata.py` — airport/airspace downloads; `find_location.py`, `get_projection_params.py` -- `mssautoplot.py` — headless batch-plot CLI; drives the msui plotting stack - (grandfathered upward dependency — do not extend it) - `migration/` — converts settings files between major config versions ## May import -Nothing from `mslib` outside `utils` — target state. Grandfathered exceptions -(`msui.constants` in config/auth/airdata/migration, the msui stack in -mssautoplot) are frozen in setup.cfg `ignore_imports`; never add new ones. +Nothing from `mslib` outside `utils` — this is the base layer, enforced by +the `gui-isolation` contract in setup.cfg. ## Invariants - New config keys: add the attribute on `MSUIDefaultConfig` AND, if dict/list shaped, the matching entry in `dict_option_structure`/`list_option_structure` and a line in `config_descriptions`. -- Everything except `qt.py`/`colordialog.py`/`mssautoplot.py` must stay - importable without Qt or a running server. +- Everything except `qt.py`/`colordialog.py` (Qt) must stay importable without Qt + or a running server. ## Verify