Last updated: 2026-03-02
Status: Active — update when adding, renaming, or archiving docs
Total documents: 51 in docs/ + 10 in docs/decisions/ + 17 in docs/assets/logo/ + 5 in docs/assets/banners/ + 7 elsewhere in repo
Reference: Issue #200 , #201
Domain
Count
Documents
Architecture & Design 8
Governance blueprint, domain boundaries, feature flags, scoring engine, search architecture, CI proposal, health-goal personalization
Diagrams 13
Architecture, ERDs, pipeline flow, QA overview, CI/CD, confidence, concern tiers, country expansion, scoring infographic + headers
Brand Assets 17
Logomark SVG variants + PNG exports, wordmark, lockup variants (horizontal + stacked, light + dark)
Banners 5
Social preview, README hero banner (SVG + PNG), badges reference
API 6
Contracts, conventions, versioning, frontend mapping, contract testing, registry
Scoring 2
Methodology (formula), engine (architecture)
Data & Provenance 5
Sources, provenance, integrity audits, EAN validation, production data
Security & Compliance 5
Root policy, audit report, access audit, privacy checklist, rate limiting
Observability & Operations 9
Monitoring, observability, log schema, alerts, on-call policy, SLOs, metrics, incident response, disaster drill
DevOps & Environment 3
Environment strategy, staging setup, Sonar config
Frontend & UX 7
UX/UI design, UX impact metrics, brand guidelines, name candidates, design system, frontend README, design refresh spec
Process & Workflow 7
Agent workflow reference, research workflow, viewing & testing, backfill standard, migration conventions, labels, country expansion
Governance & Policy 6
Feature sunsetting, performance report, performance guardrails, doc governance, repo governance, this index
Architecture Decisions 10
MADR template + 9 ADRs (stack, scoring, country isolation, pipeline, API versioning, migrations, ingredients, nutrient density, ingredient language model)
Document
Purpose
Owner Issue
Last Updated
GOVERNANCE_BLUEPRINT.md Execution governance blueprint — master plan for all GOV-* issues
#195 2026-02-24
DOMAIN_BOUNDARIES.md Domain boundary enforcement, 13 domains, ownership mapping, interface contracts
#196 2026-02-24
FEATURE_FLAGS.md Feature flag architecture — toggle registry, rollout strategy
#191 2026-02-24
SCORING_ENGINE.md Scoring engine architecture — versioned function design, formula registry, weight governance, drift detection
#189 , #198 2026-02-28
DRIFT_DETECTION.md Automated drift detection — 8-check catalog, severity levels, CI integration plan, doc freshness, migration ordering
#199 2026-03-01
SEARCH_ARCHITECTURE.md Search architecture — pg_trgm, tsvector, ranking, synonym management
#192 2026-02-24
CI_ARCHITECTURE_PROPOSAL.md CI pipeline design proposal
—
2026-02-23
HEALTH_GOAL_PERSONALIZATION.md Health-goal personalization design — goal taxonomy, personalization model, MVP scope, privacy, copy safety
#892 2026-03-16
Location: docs/diagrams/
Toolchain: Mermaid CLI (@mermaid-js/mermaid-cli) → SVGO optimization
Source files: .mmd (Mermaid markup) — regenerate SVGs via npx @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg
File
Purpose
Owner Issue
Last Updated
architecture-overview.svg Architecture overview — data flow, components, key stats (light mode)
#426 2026-03-13
architecture-overview-dark.svg Architecture overview — dark mode variant for GitHub dark theme
#426 2026-03-13
architecture-overview.mmd Mermaid source for architecture overview (light mode)
#426 2026-03-13
architecture-overview-dark.mmd Mermaid source for architecture overview (dark mode)
#426 2026-03-13
erd-full.svg Full ERD — 30+ tables across 5 domains, Crow's foot notation (light)
#428 2026-03-13
erd-full-dark.svg Full ERD — dark mode variant for GitHub dark theme
#428 2026-03-13
erd-core.svg Core ERD — 7 product-domain tables, simplified view (light)
#428 2026-03-13
erd-core-dark.svg Core ERD — dark mode variant for GitHub dark theme
#428 2026-03-13
erd-full.mmd Mermaid source for full ERD (light mode)
#428 2026-03-13
erd-full-dark.mmd Mermaid source for full ERD (dark mode)
#428 2026-03-13
erd-core.mmd Mermaid source for core ERD (light mode)
#428 2026-03-13
erd-core-dark.mmd Mermaid source for core ERD (dark mode)
#428 2026-03-13
pipeline-flow.svg Pipeline flow — OFF API to SQL generation to DB execution
#429 2026-03-13
ci-cd-pipeline.svg CI/CD pipeline — 19 workflows, gates, triggers, artifact flow
#429 2026-03-13
qa-overview.svg QA overview — 48 suites, 747 checks organized by domain
#429 2026-03-13
confidence-model.svg Confidence scoring — 6 components, composite 0-100, band assignment
#429 2026-03-13
concern-tiers.svg EFSA concern tiers — 4-tier additive classification with examples
#429 2026-03-13
country-expansion.svg Country expansion — PL primary + DE micro-pilot architecture
#429 2026-03-13
pipeline-flow.mmd Mermaid source for pipeline flow
#429 2026-03-13
ci-cd-pipeline.mmd Mermaid source for CI/CD pipeline
#429 2026-03-13
qa-overview.mmd Mermaid source for QA overview
#429 2026-03-13
confidence-model.mmd Mermaid source for confidence model
#429 2026-03-13
concern-tiers.mmd Mermaid source for concern tiers
#429 2026-03-13
country-expansion.mmd Mermaid source for country expansion
#429 2026-03-13
headers/header-architecture.svg Section banner — Architecture (800x120px, brand gradient)
#429 2026-03-13
headers/header-scoring.svg Section banner — Scoring
#429 2026-03-13
headers/header-api.svg Section banner — API Reference
#429 2026-03-13
headers/header-qa.svg Section banner — Quality Assurance
#429 2026-03-13
headers/header-deployment.svg Section banner — Deployment
#429 2026-03-13
scoring-v32-infographic.svg Scoring v3.2 infographic — 9 factors, weights, bands, examples (light)
#427 2026-03-13
scoring-v32-infographic-dark.svg Scoring v3.2 infographic — dark mode variant
#427 2026-03-13
scoring-v32-breakdown.svg Scoring v3.2 breakdown — factor weights stacked bar + detail table
#427 2026-03-13
Location: docs/assets/logo/
Source: SVG vector originals — PNG rasters generated via sharp
Location: docs/assets/banners/
Source: SVG vector originals — PNG rasters generated via sharp
Document
Purpose
Owner Issue
Last Updated
API_CONTRACTS.md API surface contracts — response shapes, hidden columns, 20+ RPC functions
#197 2026-02-24
API_CONVENTIONS.md RPC naming convention, breaking change definition, security standards
#234 2026-02-24
API_VERSIONING.md API deprecation & versioning policy — function-name versioning, sunset timelines
#234 2026-02-24
FRONTEND_API_MAP.md Frontend-to-API mapping reference — which pages call which RPCs
#197 2026-02-13
CONTRACT_TESTING.md API contract testing strategy — pgTAP patterns, response shape validation
#197 2026-02-24
api-registry.yaml Structured registry of all 191 API functions (YAML machine-readable)
#197 2026-02-24
Document
Purpose
Owner Issue
Last Updated
SCORING_METHODOLOGY.md v3.3 scoring formula — 9 factors, weights, ceilings, bands, nutrient density bonus
#189 2026-02-12
SCORING_ENGINE.md Scoring engine architecture — function versioning, regression testing
#189 2026-02-24
Relationship: SCORING_METHODOLOGY.md defines the formula (what is computed). SCORING_ENGINE.md defines the architecture (how it is maintained, versioned, and tested). No redundancy — they serve different audiences.
Document
Purpose
Owner Issue
Last Updated
DATA_SOURCES.md Source hierarchy & validation workflow — OFF API, manual entry
#193 2026-02-12
DATA_PROVENANCE.md Data provenance & freshness governance — lineage tracking, staleness detection
#193 2026-02-24
DATA_INTEGRITY_AUDITS.md Ongoing data integrity audit framework — nightly checks, contradiction detection
#184 2026-02-22
EAN_VALIDATION_STATUS.md EAN coverage tracking — 997/1,025 (97.3%)
Data domain
2026-02-24
PRODUCTION_DATA.md Production data management — sync, backup, restore procedures
DevOps domain
2026-02-24
Relationship: DATA_SOURCES.md catalogs where data comes from. DATA_PROVENANCE.md governs how freshness and lineage are tracked . No redundancy.
Document
Purpose
Owner Issue
Last Updated
../SECURITY.md Root security policy — vulnerability table, reporting process
Security domain
2026-02-24
SECURITY_AUDIT.md Full security audit report — RLS, function security, headers, dependencies
#232 2026-02-23
ACCESS_AUDIT.md Data access pattern audit — table-by-role matrix, quarterly review process
#235 2026-02-24
PRIVACY_CHECKLIST.md GDPR/RODO compliance checklist — data inventory, retention, subject rights
#236 2026-02-24
RATE_LIMITING.md Rate limiting strategy — API abuse prevention, throttle tiers
Security domain
2026-02-23
Relationship: SECURITY.md (root) is a policy overview (required by GitHub security features). SECURITY_AUDIT.md is a detailed audit report . ACCESS_AUDIT.md focuses on access patterns . No redundancy — each has distinct scope.
Observability & Operations
Document
Purpose
Owner Issue
Last Updated
MONITORING.md Runtime monitoring — alerts, dashboards, health checks
Observability domain
2026-02-24
OBSERVABILITY.md Observability strategy — structured logging, tracing, metrics pipeline
Observability domain
2026-02-23
SLO.md Service Level Objectives — availability, latency, error rate targets
Observability domain
2026-02-24
METRICS.md Metrics catalog — application metrics, infrastructure metrics, business metrics
Observability domain
2026-02-24
INCIDENT_RESPONSE.md Incident response playbook — severity, escalation, runbooks, post-mortem
#231 2026-02-24
LOG_SCHEMA.md Structured log schema & error taxonomy — error codes, severity, retention, validation
#210 2026-03-04
ALERT_POLICY.md Alert escalation policy, query regression detection, index drift monitoring
#211 2026-03-04
monitoring/alerts.ymlMachine-readable alert definitions (source of truth for ALERT_POLICY.md)
#332 2026-03-05
ON_CALL_POLICY.md On-call & alert ownership — routing, ack targets, triage labels, quiet hours
#233 2026-03-04
DISASTER_DRILL_REPORT.md Disaster recovery drill report — test results, findings, remediation
Observability domain
2026-02-23
.github/workflows/dr-drill.ymlAutomated DR drill — monthly cron + manual, disposable PostgreSQL rebuild
#333 2026-03-05
Document
Purpose
Owner Issue
Last Updated
ENVIRONMENT_STRATEGY.md Local/staging/production environment strategy
DevOps domain
2026-02-22
STAGING_SETUP.md Staging environment setup guide — scripts, sync workflow, configuration
DevOps domain
2026-02-24
SONAR.md SonarCloud configuration & quality gates
DevOps domain
2026-02-23
Relationship: ENVIRONMENT_STRATEGY.md defines the overall strategy (3 environments). STAGING_SETUP.md provides operational setup steps for staging specifically. Complementary, not redundant.
Document
Purpose
Owner Issue
Last Updated
UX_UI_DESIGN.md UI/UX design guidelines — color system, components, layouts
Frontend domain
2026-02-24
UX_IMPACT_METRICS.md UX measurement standard — event catalog, metric templates, performance budget
Frontend domain
2026-02-24
BRAND_GUIDELINES.md Brand guidelines — 14-section visual identity reference (colors, typography, motion, accessibility, dark mode, assets)
#410 2026-03-14
NAME_CANDIDATES.md App name research — ~419 candidates scored across 41 rounds, domain availability checks
#539 2025-07-21
../frontend/docs/DESIGN_SYSTEM.md Frontend design system — Tailwind tokens, component patterns
Frontend domain
2026-02-17
../frontend/README.md Frontend project overview — setup, scripts, architecture
Frontend domain
2026-02-24
DESIGN_REFRESH_SPEC.md Mobile-first design system & UX refresh spec — component redesign rules, layout principles, implementation order
Frontend domain
2026-03-14
Document
Purpose
Owner Issue
Last Updated
RESEARCH_WORKFLOW.md Data collection lifecycle — manual + automated OFF pipeline
Process domain
2026-02-24
VIEWING_AND_TESTING.md Queries, Studio UI, test runner guide
Process domain
2026-02-24
BACKFILL_STANDARD.md Backfill orchestration standard — migration templates, validation patterns
#208 2026-03-03
MIGRATION_CONVENTIONS.md Migration safety, trigger naming, lock risk, idempotency standards
#203 , #207 2026-03-02
LABELS.md GitHub labeling conventions — issue/PR label taxonomy
Process domain
2026-02-23
COUNTRY_EXPANSION_GUIDE.md Multi-country expansion protocol — PL active, DE micro-pilot
#148 2026-02-24
AGENT_WORKFLOW.md Agent/AI workflow reference — execution protocol, command quick-reference, domain matrix, priority definitions
#200 2026-03-02
Repo root script: setup-env.ps1.env → PowerShell session loader with -Verify connectivity checks and -ShowValues masked display. Dot-source with . .\setup-env.ps1.
Document
Purpose
Owner Issue
Last Updated
FEATURE_SUNSETTING.md Feature retirement criteria, cleanup policy, quarterly hygiene review
#237 2026-02-24
PERFORMANCE_REPORT.md Performance audit — query patterns, scale projections, benchmark findings
Governance domain
2026-02-24
PERFORMANCE_GUARDRAILS.md Performance guardrails — query budgets, index policy, scale projections
Governance domain
2026-02-23
REPO_GOVERNANCE.md Repo structure rules, root cleanliness, change checklists, CI alignment
Governance domain
2026-02-25
DOCUMENTATION_GOVERNANCE.md Documentation ownership, versioning, deprecation, drift prevention cadence
#201 2026-03-01
INDEX.md
This file — canonical documentation map
#200 2026-03-01
Architecture Decisions (ADRs)
Location: docs/decisions/
Template: MADR 3.0 (Markdown Any Decision Records)
Convention: Files named NNN-short-title.md with sequential numbering
Other Repository Documents Pairs investigated for overlap during the 2026-02-28 audit:
Pair
Assessment
Verdict
SECURITY.md (root) ↔ SECURITY_AUDIT.md
Root = policy overview; Audit = detailed report
No redundancy — distinct scope
DATA_SOURCES.md ↔ DATA_PROVENANCE.md
Sources = where data comes from; Provenance = freshness governance
No redundancy — complements
SCORING_METHODOLOGY.md ↔ SCORING_ENGINE.md
Methodology = formula; Engine = architecture
No redundancy — what vs how
ENVIRONMENT_STRATEGY.md ↔ STAGING_SETUP.md
Strategy = overall design; Setup = operational steps
No redundancy — complements
MONITORING.md ↔ OBSERVABILITY.md
Monitoring = alerts/dashboards; Observability = logging/tracing/metrics pipeline
No redundancy — overlapping domain, distinct focus
OBSERVABILITY.md ↔ LOG_SCHEMA.md
Observability = strategy/format; Log Schema = error codes/taxonomy/DB registry
No redundancy — format vs taxonomy
METRICS.md ↔ UX_IMPACT_METRICS.md
Metrics = infra/app metrics; UX Impact = UX-specific measurement
No redundancy — different audiences
PERFORMANCE_REPORT.md ↔ PERFORMANCE_GUARDRAILS.md
Report = audit findings; Guardrails = policy/budgets
No redundancy — snapshot vs policy
ALERT_POLICY.md ↔ ON_CALL_POLICY.md
Alert Policy = escalation matrix/thresholds; On-Call = ownership/ack targets/labels
No redundancy — what triggers vs who responds
REPO_GOVERNANCE.md ↔ GOVERNANCE_BLUEPRINT.md
Repo Governance = structure/hygiene/checklists; Blueprint = execution governance
No redundancy — repo rules vs project management
REPO_GOVERNANCE.md ↔ DOCUMENTATION_GOVERNANCE.md
Repo Governance = structure/root/CI; Doc Governance = doc ownership/drift/versioning
No redundancy — repo-wide vs doc-specific
Files checked for references to deprecated elements (scored_at, column_metadata). Note: compute_unhealthiness_v31 was dropped in migration 20260314000100_remove_legacy_v31_scoring.sql.
File
Hits
Assessment
FEATURE_SUNSETTING.md
2
column_metadata referenced as already-cleaned-up example — intentional
SCORING_ENGINE.md
5
References to v3.1 as historical context in version evolution — intentional
SCORING_METHODOLOGY.md
4
References to v3.1 as previous version in changelog section — intentional
SECURITY_AUDIT.md
1
v31 row removed (function dropped); remaining v3.2 reference — valid
UX_UI_DESIGN.md
1
Minor v3.1 reference in historical context — intentional
Result: No stale or misleading obsolete references found. All hits are intentional historical context.
Removed Documents (No Longer Present) The following files were referenced in early project phases but have been superseded or consolidated:
Former File
Status
Successor
DATA_ACQUISITION_WORKFLOW.mdSuperseded
Content merged into RESEARCH_WORKFLOW.md
EAN_EXPANSION_PLAN.mdSuperseded
Content merged into EAN_VALIDATION_STATUS.md
FULL_PROJECT_AUDIT.mdSuperseded
One-time audit; findings incorporated into GOVERNANCE_BLUEPRINT.md
TABLE_AUDIT_2026-02-12.mdSuperseded
One-time snapshot; findings incorporated into current schema documentation
PLATFORM_MATURITY_MODEL.mdSuperseded
Content absorbed into GOVERNANCE_BLUEPRINT.md
Every active document in docs/ should include a header block:
# Document Title
> ** Last updated:** YYYY-MM-DD> ** Status:** Active | Deprecated | Archived> ** Owner issue:** #NNN (or "—" if no specific issue)When modifying code in a domain, check the corresponding doc:
Code Change
Document to Check
Scoring formula weights/ceilings
SCORING_METHODOLOGY.md
API function signature or response
API_CONTRACTS.md, FRONTEND_API_MAP.md
New migration
copilot-instructions.md (schema section)
New country added
COUNTRY_EXPANSION_GUIDE.md
New user-facing table
PRIVACY_CHECKLIST.md, ACCESS_AUDIT.md
Environment configuration
ENVIRONMENT_STRATEGY.md
CI workflow changes
CI_ARCHITECTURE_PROPOSAL.md
Create in docs/ with frontmatter header
Add entry to this INDEX.md in the appropriate domain section
Add entry to copilot-instructions.md project layout (docs section)
Add CHANGELOG.md entry under [Unreleased] → Documentation
Add > **Status:** Archived — [reason] to the document header
Move the INDEX.md entry to the "Removed Documents" section
Optionally move the file to docs/archive/ (create directory if needed)
Update copilot-instructions.md project layout
