diff --git a/docs/architecture/vg-core-inventory.md b/docs/architecture/vg-core-inventory.md new file mode 100644 index 0000000..51e870e --- /dev/null +++ b/docs/architecture/vg-core-inventory.md @@ -0,0 +1,50 @@ +# VG-Core Inventory + +## Bereits vorhandener Core + +- `src/core/README.md` +- `src/core/module-registry.js` + +## Core-Kandidaten, noch nicht verschieben + +| Pfad | Vermutete Core-Funktion | Risiko bei Verschiebung | Kurze Begründung | +| --- | --- | --- | --- | +| `src/background/utils.js` | Gemeinsame Hilfsfunktionen für Hashing und stabile Serialisierung | mittel | Wird als generische Grundlage genutzt, hängt aber aktuell implizit an der Script-Ladereihenfolge im Background-Kontext. | +| `src/background/settings.js` | Globale Enable/Disable-Einstellungen | mittel | Enthält modulübergreifend wirkende Schalter, ist aber noch konkret an Consent- und Request-Monitoring benannt. | +| `src/background/maintenance-guard.js` | Gemeinsame Evidence-Schreibsperre für Wartungs-/Admin-Vorgänge | niedrig | Kapselt eine kleine globale Sperrlogik ohne direkte Fachauswertung; Abhängigkeiten wirken überschaubar. | +| `src/background/db/db-constants.js` | Gemeinsame IndexedDB-Namen, Version und Store-Liste | hoch | Zentral für DB-Version und Store-Namen; jede Verschiebung berührt Ladeordnung und Migrationsrisiko. | +| `src/background/db/db-core.js` | Gemeinsames IndexedDB-Öffnen und Store-Anlage | hoch | Enthält konkrete Object-Store-Erzeugung inklusive Consent-, Request- und GVL-Stores; sehr sensibel für DB-Kompatibilität. | +| `src/background/db/db-retention.js` | Gemeinsame Evidence-Zählung und Retention-Helfer | mittel | Arbeitet über alle Evidence-Stores und wirkt infrastrukturell, ist aber an die aktuelle Store-Liste gekoppelt. | +| `src/background/db/db-record-locks.js` | Gemeinsame Record-Lock-Operationen für Evidence-Daten | mittel | Modulübergreifende Sperrlogik, aber direkt an alle Evidence-Stores und deren Felder gebunden. | +| `src/background/gvl/gvl-catalog-normalizer.js` | Normalisierung gemeinsamer GVL-Katalogdaten | hoch | Könnte später gemeinsame Vendor-/GVL-Wissensbasis stützen, ist aktuell aber eng mit GVL-Snapshots und IndexedDB-Schreibzugriff verbunden. | +| `src/background/gvl/gvl-vendor-normalizer.js` | Normalisierung gemeinsamer Vendor-Stammdaten | hoch | Potenziell modulübergreifend wertvoll, aber derzeit aus konkreten GVL-Snapshots abgeleitet und DB-gekoppelt. | +| `src/background/gvl/gvl-vendor-relationship-normalizer.js` | Normalisierung gemeinsamer Vendor-Beziehungen | hoch | Potenziell Teil einer Wissensbasis, aber noch an Snapshot-Verarbeitung und Store-Struktur gebunden. | + +Hinweis: `src/shared/`, `src/common/` und `src/utils/` wurden im aktuellen Bestand nicht gefunden. + +## Eindeutig nicht Core + +- `src/modules/vg-observe/`: VG-Observe ist das aktive Fachmodul für Beobachtung / Consent / TCF / GVL / Evidence. +- `src/modules/vg-block/`: Fachmodul für Block-/Interventionslogik. +- `src/modules/vg-graph/`: Fachmodul für Graphvisualisierung. +- `src/background.js`: Enthält VG-Observe-spezifische TCF-/CMP-Beobachtung, TC-String-Auswertung, Consent-State-Persistenz, GVL-Fetch und Evidence-Persistenz. +- `src/background/consent-memory.js`: Fachliche Zwischenspeicherung beobachteter TCF-/Consent-Zustände. +- `src/background/request-observer.js`: Request-Beobachtung und Korrelation mit Consent-State. +- `src/background/request-fingerprint.js`: Request-Fingerprinting mit Consent-Query-Parametern. +- `src/background/gvl-service.js`: Konkrete GVL-Snapshot-Erfassung, Hashing, Speicherung und Event-Erzeugung. +- `src/content/tcf-listener.js`: Content-seitige TCF-/CMP-Beobachtung. +- `src/injected/tcf-bridge.js`: Injected Bridge zur TCF-/CMP-Erfassung und TC-String-Capture. +- `src/popup/`: UI-spezifische Popup-Logik und Darstellung. +- `src/dashboard/`: UI-spezifische Dashboard-, Admin- und Evidence-Ansichten. + +## Altbegriffe als Fundstellen + +- `VendorGet-IV`: gefunden in `src/popup/popup.html`, `src/popup/popup.js`, `src/dashboard/dashboard.html`, `src/dashboard/dashboard.js`, `src/background/request-observer.js`. +- `VG-IV`: gefunden in `src/dashboard/dashboard.html`, `src/dashboard/dashboard.js`, `src/background/request-observer.js`. +- `vendorget_iv`: gefunden in `src/background/db/db-constants.js`. + +Diese Altbegriffe werden hier nur dokumentiert und nicht umbenannt. + +## Nächster risikoarmer Schritt + +Als nächsten kleinen Schritt eine zweite reine Dokumentationsdatei oder einen Abschnitt ergänzen, der die aktuelle Script-Ladereihenfolge und Abhängigkeiten der Background-Dateien beschreibt. Kein Refactor, keine Verschiebung, keine DB-Migration. diff --git a/docs/architecture/vg-core-load-order.md b/docs/architecture/vg-core-load-order.md new file mode 100644 index 0000000..e6b9c94 --- /dev/null +++ b/docs/architecture/vg-core-load-order.md @@ -0,0 +1,68 @@ +# VG-Core Load Order + +## Manifest-Ladereihenfolge + +Die Background-Scripts werden laut `manifest.json` in dieser Reihenfolge geladen: + +| Reihenfolge | Script | Einordnung | +| --- | --- | --- | +| 1 | `src/core/module-registry.js` | Core | +| 2 | `src/modules/vg-observe/module.js` | Fachmodul | +| 3 | `src/background/db/db-constants.js` | Core-Kandidat | +| 4 | `src/background/db/db-core.js` | Core-Kandidat | +| 5 | `src/background/gvl/gvl-vendor-normalizer.js` | Core-Kandidat | +| 6 | `src/background/gvl/gvl-vendor-relationship-normalizer.js` | Core-Kandidat | +| 7 | `src/background/gvl/gvl-catalog-normalizer.js` | Core-Kandidat | +| 8 | `src/background/db/db-retention.js` | Core-Kandidat | +| 9 | `src/background/db/db-record-locks.js` | Core-Kandidat | +| 10 | `src/background/utils.js` | Core-Kandidat | +| 11 | `src/background/settings.js` | Core-Kandidat | +| 12 | `src/background/maintenance-guard.js` | Core-Kandidat | +| 13 | `src/background/consent-memory.js` | Fachmodul | +| 14 | `src/background/request-fingerprint.js` | Fachmodul | +| 15 | `src/background/request-observer.js` | Fachmodul | +| 16 | `src/background/gvl-service.js` | Fachmodul | +| 17 | `src/background.js` | Fachmodul | + +## Globale Abhängigkeiten + +- `globalThis.VGCoreModuleRegistry`: wird in `src/core/module-registry.js` gesetzt und in `src/modules/vg-observe/module.js` zur Registrierung von `VGObserveModule` verwendet. +- `globalThis.VGObserveModule`: wird in `src/modules/vg-observe/module.js` gesetzt. +- `globalThis.VendorGetGvlService`: wird in `src/background/gvl-service.js` gesetzt und in `src/background.js` für `ingestGvlSnapshot` verwendet. +- `globalThis.normalizeGvlVendorsFromSnapshot` und `globalThis.normalizeLatestGvlSnapshotVendors`: werden in `src/background/gvl/gvl-vendor-normalizer.js` gesetzt. +- `globalThis.normalizeGvlVendorRelationshipsFromSnapshot` und `globalThis.normalizeLatestGvlVendorRelationships`: werden in `src/background/gvl/gvl-vendor-relationship-normalizer.js` gesetzt. +- `globalThis.normalizeGvlCatalogsFromSnapshot` und `globalThis.normalizeLatestGvlCatalogs`: werden in `src/background/gvl/gvl-catalog-normalizer.js` gesetzt. +- `browser.runtime.onMessage` und `browser.webRequest.onBeforeRequest`: werden in `src/background.js` registriert. +- `browser.storage.local.get` und `browser.storage.local.set`: werden in `src/background/settings.js` verwendet. +- `indexedDB.open` und `indexedDB.deleteDatabase`: werden in `src/background/db/db-core.js` verwendet. +- `crypto.subtle.digest` und `TextEncoder`: werden in `src/background/utils.js` und `src/background/gvl-service.js` verwendet. +- `fetch`: wird in `src/background.js` für den offiziellen IAB-GVL-Abruf verwendet. +- `URL`: wird in `src/background/request-fingerprint.js` und `src/background/request-observer.js` zur Request-Auswertung verwendet. +- `atob`: wird in `src/background.js` beim Decoding von TC-String-Core-Metadaten verwendet. + +Weitere implizite globale Funktionsabhängigkeiten entstehen durch nicht-modulare Script-Ladung: + +- `src/background/db/db-core.js` erwartet `VENDORGET_DB_NAME` und `VENDORGET_DB_VERSION` aus `src/background/db/db-constants.js`. +- `src/background/db/db-retention.js` und `src/background/db/db-record-locks.js` erwarten `VENDORGET_EVIDENCE_STORE_NAMES` aus `src/background/db/db-constants.js`. +- `src/background/request-fingerprint.js` erwartet `sha256Hex` und `stableStringify` aus `src/background/utils.js`. +- `src/background/request-observer.js` erwartet `isRequestMonitoringEnabled`, `isEvidenceWriteSuspended`, `buildObservedRequestFingerprint`, `buildObservedRequestFingerprintSource`, `getLatestConsentStateForRequest` und `persistObservedRequest`. +- `src/background.js` erwartet unter anderem `handleObservedRequest`, `isConsentCaptureEnabled`, `rememberLatestTcfPing`, `getLatestTcfPing`, `sha256Hex`, `stableStringify`, `rememberLatestConsentState`, `openVendorGetDb`, Retention-/Lock-Funktionen und `VendorGetGvlService`. + +## Core-relevante Risiken + +- Ladeordnungsrisiko: `src/modules/vg-observe/module.js` registriert sich nur, wenn `globalThis.VGCoreModuleRegistry` bereits existiert. Die aktuelle Reihenfolge erfüllt das, ist aber empfindlich gegen Manifest-Änderungen. +- Implizite globale Abhängigkeiten: Viele Background-Scripts exportieren keine Module, sondern stellen Funktionen durch gemeinsame Script-Ausführung bereit. Verschiebungen können dadurch Laufzeitfehler erzeugen, ohne dass Imports brechen. +- DB-Konstanten / DB-Version: `src/background/db/db-constants.js` definiert `VENDORGET_DB_VERSION = 5` und die Store-Namen. `src/background/db/db-core.js` nutzt diese Werte direkt für `indexedDB.open` und Store-Anlage. +- Kopplung zwischen Core-Kandidaten und VG-Observe: DB-, Retention-, Record-Lock-, Settings- und GVL-Normalizer-Dateien wirken infrastrukturell, enthalten aber Namen, Stores oder Datenflüsse aus Consent, Request, Evidence und GVL-Snapshot-Logik. +- GVL-Kopplung: Normalizer können später Teil einer gemeinsamen Wissensbasis sein, sind aktuell aber an Snapshot-Stores und Background-DB-Zugriffe gekoppelt. + +## Nicht ändern + +- keine Script-Reihenfolge ändern +- keine `manifest.json` ändern +- keine DB-Version ändern +- keine Dateien verschieben + +## Nächster risikoarmer Schritt + +Als nächsten kleinen Schritt eine reine Dokumentations-Tabelle ergänzen, die je Background-Script die erwarteten vorausgehenden globalen Funktionen und die bereitgestellten globalen Funktionen beschreibt. Kein Refactor, keine Migration, keine Umbenennung. diff --git a/docs/architecture/vg-core-scope.md b/docs/architecture/vg-core-scope.md new file mode 100644 index 0000000..d2d4d65 --- /dev/null +++ b/docs/architecture/vg-core-scope.md @@ -0,0 +1,34 @@ +# VG-Core Scope + +## Zuständigkeit von VG-Core + +- Modul-Registry +- gemeinsame Navigation / UI-Shell +- gemeinsame IndexedDB-Grundlagen +- globale Enable/Disable-Logik +- gemeinsame Evidence-Timeline +- gemeinsame Export-Grundlagen +- gemeinsame Vendor-/GVL-Wissensbasis, soweit modulübergreifend sinnvoll + +## Nicht VG-Core + +- TCF-/CMP-Beobachtung +- TC-String-Erfassung +- Consent-State-Persistenz als Fachlogik +- konkrete GVL-Snapshot-Erfassung als VG-Observe-Fachlogik +- Block-/Rewrite-Interventionen +- Graphvisualisierung +- spekulative AdTech-Bewertungen + +## Aktueller Stand + +- src/core/module-registry.js existiert bereits +- src/modules/vg-observe/module.js registriert VG-Observe bereits +- mehrere Core-Kandidaten liegen aktuell noch unter src/background/ +- keine Dateien werden in diesem Schritt verschoben + +## Nomenklatur + +- Aktiver Modulname: VG-Observe +- Historische Bezeichnung VG-IV nicht mehr aktiv verwenden +- Altbegriffe dürfen zunächst nur als Fundstellen dokumentiert werden