From 16362c852846fe16b70e02e8b09d73b012e38ca2 Mon Sep 17 00:00:00 2001 From: Paul Golmann Date: Fri, 26 Jun 2026 20:49:18 +0200 Subject: [PATCH] docs: remove CURRENT_VS_TARGET status matrix Planned work belongs in GitHub issues; current state stays in the existing docs and package READMEs. Drop the matrix doc and update cross-links, contributor guidance, and the docs index accordingly. Signed-off-by: Paul Golmann --- docs/ACCESSIBILITY.md | 16 ++-- docs/README.md | 19 ++-- docs/architecture/CURRENT_VS_TARGET.md | 81 ----------------- docs/architecture/ECOSYSTEM.md | 89 +++++++++---------- docs/architecture/PRINCIPLES.md | 3 +- .../004-redux-in-core-react-state-in-ui.md | 1 - .../decisions/007-ui-styling-strategy.md | 3 +- .../decisions/008-i18n-approach.md | 1 - .../decisions/009-native-css-over-scss.md | 1 - docs/architecture/decisions/README.md | 1 - docs/development/CONTRIBUTING.md | 5 +- docs/development/STANDARDS.md | 7 +- docs/ecosystem/GIS_STACK_CHOICES.md | 2 +- docs/ecosystem/POSITIONING.md | 2 +- 14 files changed, 70 insertions(+), 161 deletions(-) delete mode 100644 docs/architecture/CURRENT_VS_TARGET.md diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md index b0ebdba3..1c04c9ae 100644 --- a/docs/ACCESSIBILITY.md +++ b/docs/ACCESSIBILITY.md @@ -7,14 +7,14 @@ tree has **not** completed a formal WCAG audit. ## Status (June 2026) -| Area | Status | -| ------------------------------------ | ------------------------------------------------------------------------------------------------ | -| Formal WCAG 2.x conformance audit | **Not completed** | -| Keyboard use in map/list UI | Partial — varies by component | -| Screen reader support for map canvas | **Limited** — OpenLayers canvas model | -| Focus management in modals/overlays | Partial (e.g. focus-trap in some UI) | -| Colour contrast | **Host-dependent** — theming via CSS | -| Automated a11y tests in CI | Planned (Playwright a11y checks — see [Current vs target](../architecture/CURRENT_VS_TARGET.md)) | +| Area | Status | +| ------------------------------------ | ------------------------------------- | +| Formal WCAG 2.x conformance audit | **Not completed** | +| Keyboard use in map/list UI | Partial — varies by component | +| Screen reader support for map canvas | **Limited** — OpenLayers canvas model | +| Focus management in modals/overlays | Partial (e.g. focus-trap in some UI) | +| Colour contrast | **Host-dependent** — theming via CSS | +| Automated a11y tests in CI | Planned (Playwright a11y checks) | --- diff --git a/docs/README.md b/docs/README.md index fa3680b3..7e1e0da0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # Mapsight documentation Mapsight is **actively evolving (WIP)**: used in controlled production deployments, not yet a turnkey product for -self-service integrators. See [Current vs target](architecture/CURRENT_VS_TARGET.md) and [Licensing](LICENSING.md). +self-service integrators. See [Licensing](LICENSING.md). --- @@ -37,20 +37,19 @@ Maintainer deployments currently exercise: - Basemap tile proxy pattern — [`TILE_PROXY`](integration/TILE_PROXY.md) - Declarative embed config + Redux runtime — [Redux architecture](../packages/core/docs/REDUX_ARCHITECTURE.md) -**Still evolving:** full Infosite Java guide, SSR sidecar standardization, i18n library choice — see -[Current vs target](architecture/CURRENT_VS_TARGET.md). +**Still evolving:** full Infosite Java guide, SSR sidecar standardization, i18n library choice — track in +[GitHub issues](https://github.com/open-mapsight/mapsight/issues). --- ## Architecture -| Document | About | -| --------------------------------------------------------- | ------------------------------------------- | -| [ECOSYSTEM.md](architecture/ECOSYSTEM.md) | Technical deployment stack, repos, basemaps | -| [PRINCIPLES.md](architecture/PRINCIPLES.md) | Product goals and non-goals | -| [CURRENT_VS_TARGET.md](architecture/CURRENT_VS_TARGET.md) | Implementation status matrix | -| [Decisions](architecture/decisions/README.md) | Architecture decision notes | -| [Project history](project/HISTORY.md) | Origin timeline (unverified) | +| Document | About | +| --------------------------------------------- | ------------------------------------------- | +| [ECOSYSTEM.md](architecture/ECOSYSTEM.md) | Technical deployment stack, repos, basemaps | +| [PRINCIPLES.md](architecture/PRINCIPLES.md) | Product goals and non-goals | +| [Decisions](architecture/decisions/README.md) | Architecture decision notes | +| [Project history](project/HISTORY.md) | Origin timeline (unverified) | ## Ecosystem diff --git a/docs/architecture/CURRENT_VS_TARGET.md b/docs/architecture/CURRENT_VS_TARGET.md deleted file mode 100644 index ef6ca506..00000000 --- a/docs/architecture/CURRENT_VS_TARGET.md +++ /dev/null @@ -1,81 +0,0 @@ -# Current vs target - -What exists in the monorepo today versus planned direction. - -> **For evaluators:** Mapsight is used in **controlled production deployments**, but the open-source tree is **WIP** — -> embed patterns, pulp, and tile-proxy are documented; OSI license, Infosite Java modules, SSR standardization, and i18n -> remain open. See [Licensing](../LICENSING.md). - -Legend: **Done** · **Partial** · **Planned** · **Out of scope** - ---- - -## Product and scope - -| Area | Current | Target | Decision | -| --------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -| Communicative embed maps | **Done** — core + ui; CMS embed pattern documented | More public examples; Infosite guide when modules reviewed | [001](decisions/001-react-over-vue.md), [010](decisions/010-audience-scope.md) | -| Geoportal product | **Out of scope** — optional adjacent Masterportal/CIVITAS | Document coexistence only | — | -| Regional embed host program | **Not productized** — third-party tenant embeds from anchor operators | Vision only — see [GIS stack choices § future feature](../ecosystem/GIS_STACK_CHOICES.md#future-feature-regional-embed-host-program) | — | -| Composable host-native UI | **Partial** — map/list/filter composition, SCSS/BEM presets | Token strategy TBD; native CSS migration TBD | [007](decisions/007-ui-styling-strategy.md), [009](decisions/009-native-css-over-scss.md) | -| Basemap delivery | **Done** — documented patterns A–D in [Ecosystem](ECOSYSTEM.md) | Keep integration guides current | — | - ---- - -## Runtime and state - -| Area | Current | Target | Decision | -| ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- | -| Redux ↔ OpenLayers sync | **Done** — see [Redux architecture](../../packages/core/docs/REDUX_ARCHITECTURE.md) | Keep reference current | [004](decisions/004-redux-in-core-react-state-in-ui.md) | -| Action taxonomy | **Done** — [Action guide](../../packages/core/docs/ACTION_GUIDE.md) | RTK slices, fewer legacy paths | [004](decisions/004-redux-in-core-react-state-in-ui.md) | -| GeoJSON feature model | **Done** | Same | [003](decisions/003-geojson-first-data-model.md) | -| Map engine | **Done** — OpenLayers | Same | [002](decisions/002-openlayers-over-maplibre.md) | -| Config validation (Zod) | **Partial** | TypeScript everywhere; Zod at config/API boundaries | [004](decisions/004-redux-in-core-react-state-in-ui.md) | -| HTTP / async loading | **Partial** — hand-rolled loaders in core + ui; TanStack Query in domain apps | fetch + Query layers; **RTK Query for core TBD** | [005](decisions/005-fetch-and-tanstack-query-over-axios.md) | -| SSR / hydration | **Partial** — sidecar SSR proven; monorepo hooks exist | Modern framework SSR + graceful fallback; **Node vs Bun TBD** | [006](decisions/006-ssr-state-hydration-goal.md) | -| i18n | **Partial** — `lang` in embed config | OSS i18n library; English-first dev, multi-locale hosts | [008](decisions/008-i18n-approach.md) | - ---- - -## Packages and apps - -| Package / app | Current | Target | -| --------------------------------------- | ----------------------------------- | ------------------------------------------------------------------- | -| `@mapsight/core` | **Done** — published | Stable semver, richer docs | -| `@mapsight/ui` | **Done** — published | Feature list sorter UX (deferred) | -| `@mapsight/traffic-style` | **Done** | Custom icon build docs | -| `@mapsight/vector-style-compiler` | **Done** — deep dive exists | — | -| `@mapsight/vite-host-embed` | **Done** — published via Changesets | Host embed Vite plugin (lib finalize, snippet markers, dev aliases) | -| `@mapsight/vite-count-aggregator-embed` | **Done** — workspace package | Count-aggregator app-shell CMS embed finalize | -| `@mapsight/count-aggregator-ui` | **Partial** | Public API package alignment | -| `apps/showcase` | **Done** | UI and integration demos | -| `starters/mapsight-host-starter` | **Beta** | Copy-out host embed reference | -| `starters/mapsight-next-starter` | **WIP** | Copy-out Next.js template | -| `starters/mapsight-vite-spa-starter` | **WIP** | Copy-out Vite SPA template | -| `apps/docs` (VitePress) | **Planned** | Browse `docs/` on site | -| Open-source license file | **Planned** | See [Licensing](../LICENSING.md) | - ---- - -## Ecosystem and integration - -| Area | Current | Target | -| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| mapsight-pulp (public) | **Done** — [open-mapsight/mapsight-pulp](https://github.com/open-mapsight/mapsight-pulp); [integration guide](../integration/PULP.md) | — | -| tile-proxy (public) | **Done** — part of [open-mapsight/mapsight-pulp](https://github.com/open-mapsight/mapsight-pulp); [integration guide](../integration/TILE_PROXY.md) | — | -| CMS integration guides | **Partial** — [CMS_PHP](../integration/CMS_PHP.md) done; Infosite pending review | Complete Infosite guide | -| Data platform docs | **Partial** — [DATA_BACKEND](../integration/DATA_BACKEND.md); platform host-operated | Expand when platform is open-sourced | -| GIS stack / positioning docs | **Done** — [GIS_STACK_CHOICES](../ecosystem/GIS_STACK_CHOICES.md), [POSITIONING](../ecosystem/POSITIONING.md) | — | -| Decision notes | **Started** — [decisions/README.md](decisions/README.md) | Keep updating as architecture changes | - ---- - -## Documentation - -| Area | Current | Target | -| ----------------------- | --------------------------------------------------------------------------------------------------- | ----------------- | -| Docs hub | **Done** — [docs/README.md](../README.md) | — | -| Architecture principles | **Done** | — | -| Decision records | **Done** | — | -| Contributor standards | **Done** — [STANDARDS](../development/STANDARDS.md), [CONTRIBUTING](../development/CONTRIBUTING.md) | — | -| Project history | **Partial** — [HISTORY](../project/HISTORY.md) | Verified timeline | diff --git a/docs/architecture/ECOSYSTEM.md b/docs/architecture/ECOSYSTEM.md index 20cb309d..b39f05d6 100644 --- a/docs/architecture/ECOSYSTEM.md +++ b/docs/architecture/ECOSYSTEM.md @@ -14,50 +14,50 @@ Typical **municipal or regional** deployment (many components are optional): ```mermaid flowchart TB - subgraph ingress [Ingress] - Proxy["Caddy / Apache reverse proxy"] - end - subgraph content [Content and delivery] - CMS["CMS e.g. Infosite TYPO3"] - end - subgraph frontend [Mapsight frontend - this monorepo] - Apps["SPAs and embed builds"] - Packages["@mapsight/core + @mapsight/ui"] - end - subgraph backend [Companion services - mapsight-pulp monorepo] - Pulp["mapsight-pulp PHP ETL"] - Platform["Host data platform optional"] - end - subgraph optional [Optional pro frontend] - GP["Geoportal e.g. Masterportal CIVITAS"] - end - subgraph data [Data infrastructure] - GS["GeoServer WMS WFS"] - Ext["External HTTP feeds"] - end - subgraph basemap [Basemap tiles] - TileProxy["tile-proxy optional"] - Upstream["OSM basemap.de geo dept XYZ"] - end - Proxy --> CMS - Proxy --> Apps - Proxy --> Pulp - Proxy --> Platform - Proxy --> GP - Proxy --> TileProxy - CMS -->|"pages embeds declarative JSON"| Apps - CMS -->|"GeoJSON content APIs"| Pulp - CMS -->|"GeoJSON content APIs"| Apps - Apps --> Packages - Apps -->|"fetch GeoJSON"| Pulp - Apps -->|"HTTP API"| Platform - Apps -->|"basemap XYZ"| TileProxy - Apps -->|"WMS raster basemap"| GS - TileProxy --> Upstream - TileProxy --> GS - GP --> GS - Pulp --> Ext - Platform --> Ext + subgraph ingress [Ingress] + Proxy["Caddy / Apache reverse proxy"] + end + subgraph content [Content and delivery] + CMS["CMS e.g. Infosite TYPO3"] + end + subgraph frontend [Mapsight frontend - this monorepo] + Apps["SPAs and embed builds"] + Packages["@mapsight/core + @mapsight/ui"] + end + subgraph backend [Companion services - mapsight-pulp monorepo] + Pulp["mapsight-pulp PHP ETL"] + Platform["Host data platform optional"] + end + subgraph optional [Optional pro frontend] + GP["Geoportal e.g. Masterportal CIVITAS"] + end + subgraph data [Data infrastructure] + GS["GeoServer WMS WFS"] + Ext["External HTTP feeds"] + end + subgraph basemap [Basemap tiles] + TileProxy["tile-proxy optional"] + Upstream["OSM basemap.de geo dept XYZ"] + end + Proxy --> CMS + Proxy --> Apps + Proxy --> Pulp + Proxy --> Platform + Proxy --> GP + Proxy --> TileProxy + CMS -->|" pages embeds declarative JSON "| Apps + CMS -->|" GeoJSON content APIs "| Pulp + CMS -->|" GeoJSON content APIs "| Apps + Apps --> Packages + Apps -->|" fetch GeoJSON "| Pulp + Apps -->|" HTTP API "| Platform + Apps -->|" basemap XYZ "| TileProxy + Apps -->|" WMS raster basemap "| GS + TileProxy --> Upstream + TileProxy --> GS + GP --> GS + Pulp --> Ext + Platform --> Ext ``` The **CMS** is both a **delivery channel** and often a **content source**: it hosts Mapsight embeds (HTML snippets or @@ -128,7 +128,6 @@ back-office tools. ## Related docs - [Principles](PRINCIPLES.md) — scope, composable UI, non-goals -- [Current vs target](CURRENT_VS_TARGET.md) — implementation status - [@mapsight/core → Redux architecture](../../packages/core/docs/REDUX_ARCHITECTURE.md) — declarative GIS runtime - [mapsight-pulp](https://github.com/open-mapsight/mapsight-pulp) — PHP companion monorepo - [tile-proxy](https://github.com/open-mapsight/mapsight-pulp) — basemap diff --git a/docs/architecture/PRINCIPLES.md b/docs/architecture/PRINCIPLES.md index 754579ad..87487147 100644 --- a/docs/architecture/PRINCIPLES.md +++ b/docs/architecture/PRINCIPLES.md @@ -1,7 +1,7 @@ # Architecture principles North-star goals for Mapsight as a **communicative, embed-first** GIS frontend. For deployment topology -see [Ecosystem](ECOSYSTEM.md); for implementation status see [Current vs target](CURRENT_VS_TARGET.md). +see [Ecosystem](ECOSYSTEM.md). --- @@ -94,6 +94,5 @@ map product shape that fits the content — not a shared GIS portal skin. ## Related - [Ecosystem](ECOSYSTEM.md) -- [Current vs target](CURRENT_VS_TARGET.md) - [Decisions](decisions/README.md) - [Licensing](../LICENSING.md) diff --git a/docs/architecture/decisions/004-redux-in-core-react-state-in-ui.md b/docs/architecture/decisions/004-redux-in-core-react-state-in-ui.md index 344c0682..a95eab0f 100644 --- a/docs/architecture/decisions/004-redux-in-core-react-state-in-ui.md +++ b/docs/architecture/decisions/004-redux-in-core-react-state-in-ui.md @@ -61,4 +61,3 @@ cache. - [`packages/ui/src/js/store/actions.ts`](../../../packages/ui/src/js/store/actions.ts) — legacy hand-rolled fetch actions (to replace) - [Decision 005](005-fetch-and-tanstack-query-over-axios.md) -- [Current vs target](../CURRENT_VS_TARGET.md#runtime-and-state) diff --git a/docs/architecture/decisions/007-ui-styling-strategy.md b/docs/architecture/decisions/007-ui-styling-strategy.md index 4476da35..fbe06484 100644 --- a/docs/architecture/decisions/007-ui-styling-strategy.md +++ b/docs/architecture/decisions/007-ui-styling-strategy.md @@ -38,8 +38,7 @@ Option **C** explicitly allows a municipal site on SCSS overrides while a domain migration ([Decision 009](009-native-css-over-scss.md)) would shift Option A toward custom properties without changing the composable goal. -Do **not** document “Mapsight uses shadcn globally” until a migration is real. Track progress -in [Current vs target](../CURRENT_VS_TARGET.md). +Do **not** document “Mapsight uses shadcn globally” until a migration is real. ## Consequences diff --git a/docs/architecture/decisions/008-i18n-approach.md b/docs/architecture/decisions/008-i18n-approach.md index f9389d13..5114f0cf 100644 --- a/docs/architecture/decisions/008-i18n-approach.md +++ b/docs/architecture/decisions/008-i18n-approach.md @@ -57,5 +57,4 @@ Until this note is updated with a library choice: ## References - [Principles → UX goals](../PRINCIPLES.md#ux-goals) -- [Current vs target](../CURRENT_VS_TARGET.md#runtime-and-state) - Planned: [POSITIONING.md](../../ecosystem/POSITIONING.md) — Masterportal i18next as reference diff --git a/docs/architecture/decisions/009-native-css-over-scss.md b/docs/architecture/decisions/009-native-css-over-scss.md index f5393761..33130fd2 100644 --- a/docs/architecture/decisions/009-native-css-over-scss.md +++ b/docs/architecture/decisions/009-native-css-over-scss.md @@ -81,4 +81,3 @@ vector-style-compiler internals. styleFunction out - [`packages/vector-style-compiler/src/js/cli.ts`](../../../packages/vector-style-compiler/src/js/cli.ts) — optional Sass pre-step only -- [Current vs target](../CURRENT_VS_TARGET.md) diff --git a/docs/architecture/decisions/README.md b/docs/architecture/decisions/README.md index 0db355b8..334a6446 100644 --- a/docs/architecture/decisions/README.md +++ b/docs/architecture/decisions/README.md @@ -48,4 +48,3 @@ is useful to preserve. ## Related - [Principles](../PRINCIPLES.md) -- [Current vs target](../CURRENT_VS_TARGET.md) diff --git a/docs/development/CONTRIBUTING.md b/docs/development/CONTRIBUTING.md index 26907705..33b2562e 100644 --- a/docs/development/CONTRIBUTING.md +++ b/docs/development/CONTRIBUTING.md @@ -55,9 +55,7 @@ Husky hooks run leak checks and lint-staged on commit/push. `013-short-title.md`. 2. Fill Context, Decision, Alternatives, Consequences — plain language, not formal committee prose. 3. Add a row to [`decisions/README.md`](../architecture/decisions/README.md) index. -4. If the decision changes maintainer status, update [`CURRENT_VS_TARGET.md`](../architecture/CURRENT_VS_TARGET.md) \* - \*Decision\*\* column. -5. Link related package docs (Redux, integration guides) in the **References** section. +4. Link related package docs (Redux, integration guides) in the **References** section. Write one for framework choices, public API/config contracts, explicit non-goals, and licensing/ecosystem alignment. Skip routine fixes and dependency bumps. @@ -71,7 +69,6 @@ Status values: **Documented** · **Open** · **Deprecated** · **Superseded by D | Change type | Update | | ----------------------- | ------------------------------------------------------------------- | | New integration pattern | `docs/integration/*` + link from [docs/README.md](../README.md) | -| Status matrix | [CURRENT_VS_TARGET.md](../architecture/CURRENT_VS_TARGET.md) | | Ecosystem/deployment | [ECOSYSTEM.md](../architecture/ECOSYSTEM.md) (public patterns only) | | Package behavior | Package `README.md` and/or `packages/*/docs/` | diff --git a/docs/development/STANDARDS.md b/docs/development/STANDARDS.md index a46ca5eb..62e0529c 100644 --- a/docs/development/STANDARDS.md +++ b/docs/development/STANDARDS.md @@ -115,13 +115,15 @@ On checkouts that include a private workspace: - `pnpm run check:no-private-leak` enforces on public branches; `pnpm-lock.yaml` must not list importers under `private/` on public branches - On **`private/*` branches**, these checks are skipped -- Merge direction: integrate **open source into private**, not the reverse — see [`private/README.md`](../../private/README.md) +- Merge direction: integrate **open source into private**, not the reverse — see [ + `private/README.md`](../../private/README.md) when present To prevent accidental leaks, this repository enforces checks locally and in CI: - Git hooks: [`.husky/pre-commit`](../../.husky/pre-commit), [`.husky/pre-push`](../../.husky/pre-push) -- Script: [`scripts/check-no-private-leak.mts`](../../scripts/check-no-private-leak.mts) — `pnpm run check:no-private-leak` +- Script: [`scripts/check-no-private-leak.mts`](../../scripts/check-no-private-leak.mts) — + `pnpm run check:no-private-leak` - CI: `no-private-leak` job in [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) **Please do not open pull requests that remove or weaken these guards.** @@ -131,7 +133,6 @@ To prevent accidental leaks, this repository enforces checks locally and in CI: ## Project docs - Architecture, integration, and contributor docs live in `docs/` -- Update [CURRENT_VS_TARGET.md](../architecture/CURRENT_VS_TARGET.md) when shipping meaningful status changes - Significant choices → [architecture/decisions/](../architecture/decisions/README.md) --- diff --git a/docs/ecosystem/GIS_STACK_CHOICES.md b/docs/ecosystem/GIS_STACK_CHOICES.md index d09e54b1..97eb2c41 100644 --- a/docs/ecosystem/GIS_STACK_CHOICES.md +++ b/docs/ecosystem/GIS_STACK_CHOICES.md @@ -77,7 +77,7 @@ Product comparison: [Positioning](POSITIONING.md). An anchor operator (city, VMZ, regional mobility agency) that **already runs Mapsight** could someday offer **limited embeds or static map exports to third parties** — multi-tenant presets, quotas, snippet builder. -**Not productized today** — [Current vs target](../architecture/CURRENT_VS_TARGET.md). +**Not productized today.** --- diff --git a/docs/ecosystem/POSITIONING.md b/docs/ecosystem/POSITIONING.md index 9a5224ac..9f3b9211 100644 --- a/docs/ecosystem/POSITIONING.md +++ b/docs/ecosystem/POSITIONING.md @@ -143,7 +143,7 @@ common library, different products and integration models. ## Regional embed host (future) Some anchor operators may someday offer **limited embeds to third-party local orgs** — **not productized today. -** [GIS stack choices § future feature](GIS_STACK_CHOICES.md#future-feature-regional-embed-host-program) · [Current vs target](../architecture/CURRENT_VS_TARGET.md). +** [GIS stack choices § future feature](GIS_STACK_CHOICES.md#future-feature-regional-embed-host-program). ---