Enhance security, accessibility, and localization in v6.1.9

.github/workflows/ci.yml

@@ -65,3 +65,26 @@ jobs:
             coverage/
             playwright-report/
             test-results/
+
+  windows-smoke:
+    runs-on: windows-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Run Windows server helper smoke tests
+        run: npx vitest run tests/unit/server-helpers.test.ts
+
+      - name: Build production bundle
+        run: npm run build:app

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [6.1.9] - 2026-04-14
+
+### Added
+
+- **Klare Recovery-Flows für beschädigte lokale Daten** — die App zeigt korrupte Settings- oder Usage-Dateien jetzt als expliziten Fehlerzustand mit direkten Reset- und Löschaktionen statt als irreführenden Leerzustand
+- **Architekturdokumentation für die aktuelle Systemstruktur** — eine neue Architekturübersicht beschreibt die Grenzen zwischen lokalem Server, Frontend, Shared-Domainlogik und Packaging für die weitere Wartung
+
+### Improved
+
+- **Barrierefreiheit und Informationsqualität in zentralen Dashboard-Flächen** — Top-Level-Filter haben jetzt stabile zugängliche Namen, Info-Buttons sind semantisch sauber von Headings getrennt, und das Help-Panel zeigt vollständig benannte und fachlich besser gruppierte Inhalte
+- **Lokalisierung und Terminologiekonsistenz in Analyse- und Tooltip-Flächen** — gemischte deutsche und englische UI-Begriffe wurden bereinigt, Tooltip-Texte lokalisiert und die verbleibenden Accessibility-/i18n-Regressionen durch zusätzliche Tests abgesichert
+- **Robustere lokale API-Grenzen und Auto-Import-Sicherheit** — mutierende Endpunkte akzeptieren nur noch erlaubte Request-Formen, Cross-Site-Zugriffe werden abgewehrt, Auto-Import verwendet keine mutierende `GET`-Route mehr, und non-loopback Binding erfordert jetzt ein explizites Remote-Opt-in
+- **Sicherere lokale Persistenz und Exportpfade** — Daten- und Settings-Dateien werden restriktiver geschrieben, CSV-Exporte escapen Sonderzeichen korrekt, und serverseitige Fatal-Load-Fehler werden bis in die UI transparent durchgereicht
+- **Nachhaltigere Architektur für Dashboard, Report und Server-Runtime** — gemeinsame Dashboard-/Report-Domainlogik, ein entschlackter Dashboard-Controller und erste Server-Module reduzieren Drift, verbessern Testbarkeit und schaffen klarere Verantwortungsgrenzen
+
+### Fixed
+
+- **Windows-Kompatibilität beim Auto-Import und Child-Process-Start** — die Runner-Ausführung funktioniert auf Windows jetzt zuverlässig ohne die zuvor fehleranfällige Prozessinitialisierung
+
 ## [6.1.8]
 
 ### Added

README.md

@@ -177,11 +177,20 @@ Commands:
 
 Environment variables:
 
-| Variable            | Description                                               |
-| ------------------- | --------------------------------------------------------- |
-| `PORT`              | Override the start port                                   |
-| `NO_OPEN_BROWSER=1` | Disable browser auto-open                                 |
-| `HOST`              | Override the bind host, for example `HOST=0.0.0.0 ttdash` |
+| Variable                | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `PORT`                  | Override the start port                                   |
+| `NO_OPEN_BROWSER=1`     | Disable browser auto-open                                 |
+| `HOST`                  | Override the bind host, for example `HOST=0.0.0.0 ttdash` |
+| `TTDASH_ALLOW_REMOTE=1` | Explicitly allow binding to a non-loopback host           |
+
+Binding to a non-loopback host such as `0.0.0.0` exposes the local dashboard API to your network, including destructive routes for local data and settings resets. TTDash now refuses that bind unless you also set `TTDASH_ALLOW_REMOTE=1`. Only use this on trusted networks.
+
+Example:
+
+```bash
+TTDASH_ALLOW_REMOTE=1 HOST=0.0.0.0 ttdash
+```
 
 ## Features
 

SECURITY.md

@@ -26,3 +26,15 @@ Please include:
 ## Response Expectations
 
 This project is maintained on a best-effort basis by a single maintainer. Reports will be reviewed as quickly as practical, but no fixed response SLA is promised.
+
+## Deployment Notes
+
+`TTDash` is intended to run as a local-first app on loopback by default. Binding it to a non-loopback host exposes local API routes for uploads, imports, resets, and report generation to your network.
+
+Non-loopback binding therefore requires an explicit opt-in:
+
+```bash
+TTDASH_ALLOW_REMOTE=1 HOST=0.0.0.0 ttdash
+```
+
+Only use that mode on trusted networks.

docs/architecture.md

@@ -0,0 +1,67 @@
+# Architecture Overview
+
+## System Shape
+
+TTDash is a local-first product with two runtime parts:
+
+- a Node-based CLI and HTTP server exposed through `server.js`
+- a Vite/React frontend bundled into `dist/`
+
+The server owns local persistence, background instance management, auto-import execution and the HTTP API. The frontend owns interaction, filtering, visualization and user-driven import/export flows.
+
+## Architectural Boundaries
+
+### Shared Domain
+
+`shared/dashboard-domain.js` is the common source of truth for model normalization, provider resolution, filter application, aggregation and core dashboard metrics. It is used by:
+
+- frontend data transforms and calculations in `src/lib/*`
+- server-side PDF report generation in `server/report/*`
+
+This boundary exists to keep dashboard and report output aligned for the same underlying data.
+
+### Frontend Page Composition
+
+The dashboard page is split into:
+
+- `src/hooks/use-dashboard-controller.ts` for query orchestration, local UI state and user actions
+- `src/components/dashboard/DashboardSections.tsx` for section rendering and layout composition
+- `src/components/Dashboard.tsx` as the thin page shell
+
+The shell is responsible for state branching only:
+
+- loading
+- fatal local-state error
+- empty state
+- main dashboard
+
+### Settings Contract
+
+Dashboard preferences are driven by `shared/dashboard-preferences.json`, which is consumed by both:
+
+- `src/lib/dashboard-preferences.ts`
+- `server.js`
+
+Frontend settings normalization lives in `src/lib/app-settings.ts`. Bootstrap loading is centralized in `src/lib/api.ts` through `loadBootstrapSettings()`.
+
+## Current Server Structure
+
+`server.js` is still the public entrypoint and still owns several runtime responsibilities. The current refactor reduces contract drift and shared-domain duplication first, while keeping the published CLI stable. Further modularization of the server runtime should continue from the current seams:
+
+- runtime/bootstrap
+- persistence/settings
+- background instance lifecycle
+- HTTP helpers and route handlers
+- auto-import execution
+
+## Release and Packaging
+
+The npm package ships:
+
+- `server.js`
+- `server/`
+- `shared/`
+- `dist/`
+- `src/locales/`
+
+`shared/` is published because the report layer depends on the same domain logic as the frontend bundle.

package.json

@@ -44,6 +44,7 @@
     "server.js",
     "usage-normalizer.js",
     "server/",
+    "shared/",
     "src/locales/",
     "dist/"
   ],
@@ -103,6 +104,7 @@
     "vitest": "^4.1.3"
   },
   "dependencies": {
+    "cross-spawn": "^7.0.6",
     "i18next": "^26.0.3",
     "react-i18next": "^17.0.2",
     "react-is": "^19.2.4"