Establish project governance and architecture principles

docs/architecture/project-principles.md

@@ -0,0 +1,159 @@
+# VG-Environment — Project Principles
+
+## Core purpose
+
+VG-Environment is a local evidence and runtime reconstruction environment for consent-related browser activity.
+
+The primary project goal is NOT large-scale telemetry collection or abstract tracking analytics.
+
+The primary goal is:
+
+To technically reconstruct what was actually observed after a concrete consent decision inside the browser runtime.
+
+Core user question:
+
+"What exactly happened technically after I was shown a consent dialog and made a specific consent decision?"
+
+VG-Environment therefore focuses on:
+- technically observable runtime behavior
+- consent-state reconstruction
+- request observation
+- GVL/version preservation
+- evidence-oriented reproducibility
+- human-understandable technical reconstruction
+
+---
+
+## Evidence-first philosophy
+
+VG-Environment prioritizes:
+- observable technical reality
+- reproducibility
+- transparency
+- evidence preservation
+- explainability
+- low interpretation bias
+
+The project must avoid:
+- black-box logic
+- AI-generated assumptions
+- speculative conclusions
+- hidden heuristics
+- non-reproducible scoring systems
+- unverifiable classifications
+
+The browser runtime is treated as the primary source of truth.
+
+---
+
+## Consent-centered architecture
+
+VG-Environment is fundamentally consent-centered.
+
+The project is NOT primarily:
+- request-centered
+- statistics-centered
+- telemetry-centered
+- crawler-centered
+
+Requests are treated as:
+observed technical follow-up activity related to concrete consent states.
+
+The central reconstruction unit is therefore:
+a concrete consent event and its technically observable consequences.
+
+---
+
+## Observe vs Analysis
+
+VG-Observe is responsible for:
+- runtime visibility
+- technical observation
+- evidence capture
+- temporal reconstruction
+- technical correlation visibility
+- human-understandable evidence presentation
+
+VG-Observe may:
+- show technical facts
+- show observable relations
+- show temporal ordering
+- show observed request activity
+- show observed consent propagation
+
+VG-Observe must NOT:
+- speculate
+- classify risk
+- infer motives
+- generate legal conclusions
+- claim causality
+- invent behavioral models
+- silently interpret observations
+
+VG-Analysis is responsible for:
+- interpretation
+- discrepancy analysis
+- pattern analysis
+- hypothesis generation
+- deeper correlation models
+- later analytical evaluation
+
+The separation between Observe and Analysis is a core architectural rule.
+
+---
+
+## Human-understandable evidence
+
+The project must not devolve into:
+- raw database dumps
+- table graveyards
+- developer-only telemetry views
+
+Technical evidence must remain understandable to humans.
+
+Preferred UX principle:
+- first orientation and understandable context
+- then technical detail
+- then raw evidence/debug data
+
+Raw technical detail remains important,
+but must not dominate the primary user experience.
+
+---
+
+## Architectural direction
+
+VG-Environment intentionally prefers:
+- small modular structures
+- explicit logic
+- low hidden complexity
+- direct inspectability
+- Vanilla JavaScript
+- minimal runtime dependencies
+- local-first workflows
+
+The project intentionally avoids unnecessary:
+- framework complexity
+- bundler dependency
+- hidden build pipelines
+- runtime abstraction layers
+- architecture inflation
+
+Long-term maintainability and inspectability are more important than trend-driven architecture decisions.
+
+---
+
+## Evidence integrity
+
+Evidence integrity has priority over convenience.
+
+The system must avoid:
+- silent evidence modification
+- destructive cleanup logic
+- hidden data rewriting
+- opaque processing pipelines
+
+Stored observations should remain reproducible and explainable whenever possible.
+
+The project is designed as a technical reconstruction environment,
+not as an automated decision engine.