Domain Definition¶

The decided domain model of PackyTrace. Architecture-significant choices live in the ADRs; this page holds the domain rules and vocabulary. Codes like QAS-x and ASR-x reference Quality Attribute Scenarios and Architecturally Significant Requirements. The current web-app implementation guide describes how the frontend realizes this model today; where terms differ, this page wins.

1. Ubiquitous Language¶

1.1 Consumer side¶

1.2 Brand side¶

1.3 Out of MVP scope¶

Reward Points, Lottery Tickets and Reviews exist only in the mock UI; they are future concepts, not part of this model.

2. Subdomains¶

3. Bounded Contexts & Context Map¶

Five bounded contexts, each an independently deployed service (ADR-007). Scanning & Resolution, Provenance and Eco Scoring fold into Product Passport: all facets of "build the trusted record", sourced through one anticorruption layer. Notifications is infrastructure; the gateway is composition — neither is a context.

Solid arrows = upstream→downstream relationships (§3.2); dashed arrows = measurement facts. Raw facts stay on the consumer side; only minimum-group-size aggregates cross the privacy wall (ASR-4).

3.1 The five contexts¶

3.2 Relationships¶

3.3 External data sources¶

See ADR-003. The ACL keeps sources pluggable. The MVP uses two independent upstreams — one per passport section, each behind its own circuit breaker, so one source down ≠ both sections down (QAS-2).

GS1 is a standard we implement, not a runtime source. Brand attribution comes from the catalog's explicit GTIN → BrandId mapping populated at tenant onboarding — never from a prefix guess or a GS1 API call (GS1 lookups are rate-capped and membership-gated, unviable at scan time).

4. Tactical Design — Aggregates, Entities, Value Objects¶

One aggregate cluster per context. Value objects are immutable; everything derived is computed, never stored.

4.1 Product Passport context¶

Aggregate root: ProductCatalogEntry — identity: GTIN (per-SKU)

Invariants — identified and resolvable by GTIN; carries no consumer state (freshness and ownership belong to the Fridge).

Response model: ResolvedPassport — assembled per scan, not an aggregate:

ResolvedPassport
├── catalogEntry: ProductCatalogEntry
├── verdict?: Verdict
├── journey: TabData<Journey>
└── eco: TabData<EcoScore>

TabData<T> = Pending | Loaded<T> | Failed(reasonCode)

Failed sections make degradation explicit without polluting the stored catalog entry (QAS-1/2). EcoScore.overallScore is derived from its pillars.

Slice note (J3.4): the assembled response carries verdict as a TabData<Verdict> rather than the bare optional verdict? shown above. The Passport→Personalization call degrades to a Failed section with a reason code — unauthenticated (anonymous scan), no_profile (signed in, no Health Profile yet, the onboarding CTA), or verdict_unavailable (Personalization timed out or errored) — so the absent cases stay distinguishable to the result page's verdict hero. A verdict failure never fails the scan.

Context-local VOs: ScannedItem { gtin, lot?, serial?, expiry?, raw } — produced by the Resolver, handed to the Fridge on add. ScanRecord { scanId, visitorId, consumerRef?, gtin, brandId, scannedAt } — records the scan independently of response assembly; consumerRef is nullified on account deletion.

4.2 Personalization & Verdict context ★ core¶

Aggregate root: HealthProfile — identity: the owning Account id (one per consumer)

Invariants

• Exists only while Identity reports granted consent: created after the consent gate, erased when ConsentRevoked arrives (QAS-3).
• At most one HealthProfile per Account; exactly one PrimaryGoal.
• No consent data stored here — consent lives in Identity.

Value objects

• Verdict { grade: Good | Careful | Avoid | Unknown, reasons: VerdictReason[], goalFit }
• VerdictReason { type: allergen | condition | diet | unverified, matchedCode, severity }
• Alert { severity: high | medium | low, type, reasonCode } — presentation layers turn reason codes into localized messages

Grading rules — the verdict domain service (§6) composes versioned policies (ConditionRulePolicy, DietRulePolicy, GoalFitPolicy); the result records the ruleVersion. Expiry never affects the Verdict — it is not a judgement about fit.

GoalFitPolicy independently produces the goal-fit line from PrimaryGoal — it accompanies every grade rather than changing it.

RuleSet v1 (ruleVersion 1.0.0) — the versioned thresholds the policies above encode. Nutrition is read per 100 g/ml (how the catalog stores Digital Labels); thresholds are boundary-inclusive (a value at the cutoff conflicts). No free-text rules — only typed codes and constants, bumped under a new ruleVersion when changed.

GoalFitPolicy classifies one nutrient per goal into good | neutral | poor (at/above high → poor, at/below low → good, else neutral); goalFit is the pair { goalCode, fit }, neutral when the label is degraded or the goal code is unknown:

4.3 Fridge context¶

Aggregate root: Fridge — identity: the owning Account id (one per consumer); contains FridgeItem entities.

Entity: FridgeItem

Invariants

• Each physical item appears at most once — by serial when available, else by generated itemId; multiple items may share GTIN, lot or expiry.
• consumed and discarded are terminal; no other transitions exist.
• The monthly waste summary is a projection over ItemDiscarded events — the event-sourcing subject.

Slice note (J4, complete): the fridge-service stands up the event store — an append-only fridge_events stream plus a fridge_items current-state projection maintained in the same transaction (ADR-009).

• Add (4.1): POST /api/v1/me/fridge/items → ItemAddedToFridge, fetching the trusted ScannedItem + passport snapshot from passport's internal GET /internal/v1/scans/{scanId}/item; the single-physical-item invariant is enforced in the aggregate and by a unique index on (account_id, serial).
• Read (4.2): GET /api/v1/me/fridge returns owned items soonest-to-expire first with derived freshness — FreshnessOf(expiry, now), ≤5-day "expiring" threshold, never stored.
• Mark used/thrown (4.4): PATCH …/items/{itemId} → ItemConsumed / ItemDiscarded (terminal); the projection status flips, freeing the serial. There is no neutral removal — every removal is a used/thrown classification, so the waste count stays honest (the bare DELETE is intentionally not offered).
• Waste summary (4.5): GET …/waste-summary folds the month's ItemConsumed/ItemDiscarded facts into plain used/wasted counts.
• Expiry alerts (4.3): a scheduled in-process sweep applies the FreshnessPolicy to all active dated items and raises one alert per item per level (fridge_alerts, unique on (item_id, level) — no spam), emitting ItemExpiring/ItemExpired + AlertRaised to Kafka. The web app reads the in-app feed via GET …/alerts and dismisses with DELETE …/alerts/{id}; real push delivery still awaits notifications infrastructure.

4.4 Identity & Consent context¶

Aggregate root: Account (consumer) — accountId, email, displayName, and an append-only consentLedger[] of ConsentRecord entities { kind, granted, timestamp, method, policyVersion }. Current consent = the latest record per kind; revocation appends, never edits.

Aggregate root: VisitorIdentity — visitorId, createdAt, linkedAccountId?. Created invisibly at the first scan; linking an Account preserves all earlier activity without changing the Visitor ID (ASR-3).

Aggregate root: Brand — the tenant unit — brandId, name, and BrandUser entities, each belonging to exactly one Brand.

Three erasure triggers exist, with deliberately different scopes (QAS-3); all handlers are idempotent:

Profile deletion does not touch the consent ledger; revocation erases the profile but not the Account. Already-published aggregate batches are unlinkable by construction.

Slice note (J3.5): the ConsentRevoked → erase HealthProfile handler ships in the slice as a best-effort Kafka consumer — fire-and-forget, auto-commit, a failed or malformed message is logged and skipped, not retried. The handler is idempotent (a redelivered revocation erases nothing and emits no HealthProfileDeleted). Reliable delivery (outbox + retries + DLQ + audit) is brought forward in P3 before the account-deletion endpoint ships; the AccountDeleted trigger and the Fridge/Passport legs of the cascade are deferred to P3 as well.

4.5 Brand Analytics context¶

No domain aggregates — by design (CQRS): only read models built from privacy-safe aggregate batches, e.g. ScansPerProduct, ScanTrend, verdict distributions, % scans saved, % scanners with accounts. Every row is tenant-scoped by brand_id; no row contains a scan, visitor or consumer identity (ASR-4).

4.6 Persistence boundaries¶

See ADR-004. HealthProfile and Fridge are server-owned. Anonymous consumers persist no profile or inventory — only a pseudonymous VisitorIdentity and ScanRecords for measurement (ASR-3). Web-app localStorage is at most a cache for the Visitor ID and session, never the source of truth.

5. Domain Events¶

The canonical event catalog — these names are load-bearing: the event-sourced Fridge, the CQRS read models and the Kafka contracts in contracts/ reuse them verbatim. Raw measurement events stay on the consumer side; only BrandMetricBatchPublished crosses the privacy wall (ADR-005).

Every event uses the envelope { eventId, eventType, occurredAt, schemaVersion, correlationId, causationId, payload } (ADR-006); the table shows payloads only.

6. Domain Services & Repositories¶

6.1 Domain services¶

6.2 Repositories¶

Brand Analytics has no repositories — its read models are the CQRS query side, populated only by the wall-crossing events above.