# ClaimPrism Architecture

## Product boundary
ClaimPrism is a WordPress/WooCommerce product today, but the architecture should avoid assuming WordPress is the permanent product boundary. WordPress is the first connector/runtime, not the final platform definition.

## Current layers
### 1. Detection / scanner layer
Responsible for:
- discovering environmental marketing claims;
- identifying context/location;
- producing findings;
- assigning risk signals/priorities.

### 2. Review workflow layer (Pro)
Responsible for:
- review state;
- reviewer/owner metadata where available;
- notes;
- audit/review history;
- export/review operations.

### 3. Evidence layer (Pro)
Responsible for:
- evidence records;
- source URL / WordPress attachment references;
- lifecycle metadata;
- evidence status;
- expiry and alerting;
- audit metadata.

### 4. Governed Claim domain (Pro)
The persistent governance foundation is implemented separately from transient finding rows.

Responsibilities:
- resolve a stable governed claim identity from the scanner `claim_key`;
- group multiple finding fingerprints/usages under one governed claim;
- retain lifecycle state and governance metadata;
- retain append-only lifecycle transition events;
- provide a reusable backend domain for Claim Library, Claim Graph, drift and approval workflows.

Current identity rule:
- `fingerprint` remains the identity of a specific detected occurrence/usage;
- `claim_key` remains the normalized scanner grouping key based on rule + matched wording;
- one governed claim may therefore reference many occurrence fingerprints;
- existing Review Workflow and Evidence Repository continue to use fingerprint links and are not destructively migrated.

#### Review/Evidence aggregate bridge
Governed Claim composes the current state of existing primitives without duplicating them:
- `ClaimPrism_Governed_Claim_Aggregate` resolves the governed claim and its usages;
- current review state and review history are read through `ClaimPrism_Review_Workflow` for each linked fingerprint;
- `ClaimPrism_Evidence_Query` is a read-only model over the existing Evidence Repository table;
- evidence create/edit/delete remains owned by the validated `ClaimPrism_Evidence_Repository` implementation;
- aggregate reads reflect source-of-truth changes on the next read rather than persisting copies in Governed Claim tables.

This read model does not auto-transition lifecycle states and does not infer legal compliance or evidence sufficiency.

#### Claim Graph usage intelligence
`ClaimPrism_Claim_Graph_Usage` is the first Customer Claim Graph read model.

It composes existing Governed Claim usage edges with live source data and exposes, per usage:
- fingerprint;
- content ID/type/title where resolvable;
- first/last seen timestamps from governed usage history;
- presence state: `current`, `removed` or defensive `unknown`;
- current Review Workflow status;
- Evidence Repository count.

Presence is not copied into a new persistence table:
- `current` means the finding fingerprint is still present in the scanner source-of-truth table;
- `removed` means the finding is no longer present but the referenced WordPress content still exists;
- `unknown` is used when ClaimPrism cannot prove either state, including historical usages whose WordPress content no longer exists.

#### Approved Claim Library foundation
`ClaimPrism_Approved_Claim_Library` turns internally approved Governed Claims into reusable read-model assets without introducing a duplicate library table.

Source-of-truth rule:
- `approved_wording` remains stored on the Governed Claim;
- library entries are eligible only when lifecycle state is `approved` or `monitoring` and approved wording is non-empty;
- `approved` is an internal governance state, not a certification or legal compliance verdict.

The library exposes:
- stable governed claim identity;
- detected and approved wording;
- approval and re-review dates;
- owner/update metadata;
- Claim Graph usage summary;
- Review/Evidence workflow summary;
- deterministic search/filter/order for future UI/API use.

The library is read-only. It creates no Approved Claim persistence table and does not write scanner, Review, Evidence or lifecycle data.

#### Semantic Drift Detection foundation
`ClaimPrism_Semantic_Drift` is a deterministic read model for comparing approved wording with current live scanner wording.

The v1 comparison deliberately avoids external AI/embedding dependencies and exposes only explainable internal governance states:
- `exact`: trimmed live wording equals trimmed approved wording;
- `normalized_match`: case, punctuation and whitespace normalization proves textual equivalence;
- `changed`: normalized wording differs and should be surfaced for human review.

Only Claim Graph edges with `presence = current` are evaluated. Removed or unknown historical usages are excluded from live drift classification and counted separately as `historical_excluded`.

Source-of-truth rule:
- Governed Claim `approved_wording` is the comparison baseline;
- scanner findings provide the current live `matched_phrase`;
- Claim Graph provides usage identity/location and presence context;
- no drift state is persisted in a new table;
- missing approved wording produces a typed defensive error instead of implying approval.

Drift states are workflow signals, not legal/compliance verdicts, and this read model does not auto-transition a claim to `re_review`.

#### Approved wording reuse foundation
`ClaimPrism_Approved_Wording_Reuse` prepares controlled reuse proposals for future editor/UI workflows without mutating WordPress content.

Eligibility and source-of-truth rules:
- the governed claim must be in `approved` or `monitoring` lifecycle state;
- `approved_wording` must be non-empty and remains stored only on the Governed Claim;
- the target must exist, use a ClaimPrism-supported content type, and have an accepted editable status;
- the service composes existing Claim Graph and Semantic Drift read models rather than copying their state.

A proposal exposes:
- a stable proposal payload version;
- governed claim identity, approved wording, owner, approval and re-review metadata;
- target content ID/type/title/status/edit URL;
- already-known governed-claim usages on the same target;
- current Claim Graph usage summary;
- current Semantic Drift summary when evaluable.

The v1 reuse service is intentionally read-only. It does not call WordPress content mutation or publishing APIs, does not create a reuse persistence table, and does not imply that the target content is legally approved or certified.

#### Claim Source Location foundation
`ClaimPrism_Source_Location` resolves an existing scanner finding to the precise WordPress source field that currently contains its matched wording without redefining the finding fingerprint.

The resolver reconstructs the same source families already collected by the scanner:
- post title;
- post excerpt, including WooCommerce short description;
- post content, including WooCommerce long description;
- supported SEO title/description post meta;
- featured/product-gallery image alt text.

A resolved locator exposes:
- content ID/type and unchanged finding fingerprint;
- source type, concrete source key and source reference;
- source label;
- deterministic 1-based occurrence index inside the normalized source;
- normalized character start/end offsets;
- source signature hash for future stale-locator validation.

Resolution rules:
- unique candidates resolve directly;
- repeated or multi-source candidates use the existing scanner finding context for deterministic disambiguation when one candidate scores uniquely higher;
- unresolved content returns an explicit `unresolved` state;
- indistinguishable candidates return `ambiguous` rather than guessing;
- deleted/missing findings or content return typed defensive errors.

The resolver is read-only, creates no source-location table, does not modify scanner fingerprints or detection behavior, and performs no post/meta/media mutation. It is the prerequisite for safe future controlled editor actions.

These claim-governance read models are premium-only. Free scanning behavior remains independent of them.

### 5. Scheduling / reporting layer (Pro)
Responsible for:
- periodic scans/reports;
- evidence expiry evaluation;
- email/report deduplication where implemented.

### 6. Presentation layer
Responsible for:
- dashboard;
- findings views;
- review workflow UI;
- evidence repository UI;
- ZEODEC design system.

Presentation changes should not silently alter business rules.

## Current design rule
The ZEODEC dashboard refresh from PR #27 is merged. Major claim-governance architecture must continue in separate, bounded branches/PRs from presentation work.

## Target domain model
The central future object is a **Governed Claim** rather than a transient finding.

A governed claim should eventually be able to reference:
- stable claim ID;
- detected text and normalized meaning;
- current/approved wording;
- source locations/usages;
- product/page/content context;
- jurisdiction/market;
- risk assessment;
- evidence records;
- evidence strength/validity;
- owner/reviewer;
- lifecycle status;
- approval/re-review dates;
- decision/audit history;
- semantic drift/change events.

### Lifecycle
`Detected → Evidence required → In review → Approved → Monitoring → Re-review`

Persisted v1 lifecycle values:
- `detected`
- `evidence_required`
- `in_review`
- `approved`
- `monitoring`
- `re_review`

These states are internal governance workflow states, not legal/compliance verdicts.

The lifecycle should continue to reuse current Review Workflow and Evidence Repository primitives rather than create parallel duplicate systems.

## Future architectural capabilities
### Claim Graph
Implemented foundation:
- group repeated claim occurrences under one governed claim;
- map one governed claim to many usage edges;
- resolve current/removed/unknown usage presence;
- compose review/evidence context per usage without copying source data;
- expose approved governed claims as a searchable reusable library read model;
- deterministically compare current live wording against approved wording for drift signals;
- prepare controlled approved-wording reuse proposals for supported WordPress targets without mutating content;
- resolve current findings to precise WordPress source fields with defensive ambiguity handling.

Next Claim Graph capabilities:
- controlled editor execution using verified, non-stale source locators and explicit human confirmation;
- optional re-review workflow orchestration built on explicit human action;
- broader claim usage map/visualization when product value justifies UI work.

### Evidence Intelligence
Future evidence evaluation may classify support as:
- Strong
- Adequate
- Weak
- Missing
- Contradictory
- Expired

This should remain decision support, not legal certification.

### Jurisdiction Engine
Separate regulatory knowledge from connector-specific scanning.
Initial target jurisdictions:
- EU
- UK
- US
- Australia

A claim may have different risk/evidence requirements by market.

### Drift Detection
The deterministic backend foundation is implemented. Future work may add richer similarity signals and workflow orchestration only when explainability, testability and product value justify them.

### Pre-publication Guard
Connector-specific hooks should be able to evaluate risky or unsupported wording before publication while leaving the final editorial decision to the user.

### Regulatory Change Impact
Future rules updates should map to affected governed claims rather than merely generate generic regulatory news.

## Connector strategy
Long-term connectors:
1. WordPress/WooCommerce
2. Shopify
3. API
4. additional CMS/e-commerce platforms

Core claim/evidence/governance concepts should be reusable across connectors.

## Data/technical principles
- Prefer stable IDs and explicit relationships.
- Preserve auditability; avoid destructive history changes.
- Keep user decisions distinct from machine recommendations.
- Avoid hard-coding regulatory logic into presentation code.
- Keep connector-specific code separate from reusable domain logic where practical.
- Design migrations defensively and incrementally.
- Keep Free/Pro capability boundaries explicit.
- Keep sensitive data collection minimal.

## Testing principles
- Domain/business rules: automated integration/unit coverage where practical.
- Packaging: CI-built installable artifacts.
- WordPress compatibility: official Plugin Check.
- WooCommerce/runtime integration: automated integration workflow.
- UI: targeted local visual validation, not full manual regression on every CSS change.

## Release principle
The goal is not feature volume. Each release should increase one or more of:
- user value;
- reliability;
- workflow embedding;
- cumulative customer data/decision value;
- defensibility.