Key Flows

These sequence diagrams use the public and internal contracts defined in API Design.

1. Anonymous Scan

sequenceDiagram actor Consumer participant Web as Consumer Web App participant Gateway as API Gateway participant Passport as passport-service participant Catalog as Passport DB participant Sources as External Sources participant Measure as measurement-pipeline Consumer->>Web: Scan GS1 Digital Link Web->>Web: Decode GTIN, lot, serial, expiry Web->>Gateway: POST /api/v1/scans Gateway->>Passport: Create anonymous scan with Visitor ID Passport->>Catalog: Resolve ProductCatalogEntry and Brand Passport->>Catalog: Save ScanRecord Passport-->>Measure: ProductScanned Passport-->>Gateway: scanId + catalog entry + pending sections Gateway-->>Web: ResolvedPassport without Verdict Web-->>Consumer: Show product and Digital Label par Load Journey Passport->>Sources: Request Journey and Load Eco Passport->>Sources: Request Eco data end Web->>Gateway: GET /api/v1/scans/{scanId} Gateway->>Passport: Read assembled result Passport-->>Gateway: Updated section states Gateway-->>Web: Journey / Eco loaded or failed

The local Product Catalog provides the first response. External-source failure changes only the affected section.

When the consumer uses a camera app instead of the in-app scanner, the flow starts at the Resolver route instead: the browser opens GET /01/{gtin}/…, the gateway has passport-service parse the path and create the same scan, and the browser is redirected to the result page — everything from Resolve ProductCatalogEntry onward is identical.

2. Personalized Scan

sequenceDiagram actor Consumer participant Web as Consumer Web App participant Gateway as API Gateway participant Passport as passport-service participant Personalization as personalization-service participant ProfileDB as Personalization DB participant Measure as measurement-pipeline Consumer->>Web: Scan GS1 Digital Link Web->>Gateway: POST /api/v1/scans with bearer token Gateway->>Passport: Create scan with Account reference Passport->>Passport: Resolve catalog entry and save ScanRecord Passport->>Personalization: POST /internal/v1/verdicts<br/>Account ref + Digital Label Personalization->>ProfileDB: Load HealthProfile and rule set Personalization->>Personalization: Compute Verdict and goal-fit Personalization-->>Measure: VerdictComputed Personalization-->>Passport: Verdict Passport-->>Measure: ProductScanned Passport-->>Gateway: ResolvedPassport + Verdict Gateway-->>Web: Scan result Web-->>Consumer: Show Verdict first

The Health Profile remains inside personalization-service; Passport receives only the computed Verdict.

3. Add to Fridge

sequenceDiagram actor Consumer participant Web as Consumer Web App participant Gateway as API Gateway participant Fridge as fridge-service participant Passport as passport-service participant FridgeStore as Fridge Event Store participant Measure as measurement-pipeline Consumer->>Web: Add scanned item to Fridge Web->>Gateway: POST /api/v1/me/fridge/items<br/>{ scanId } Gateway->>Fridge: Add item for authenticated Account Fridge->>Passport: GET /internal/v1/scans/{scanId}/item Passport-->>Fridge: Trusted ScannedItem + passport snapshot Fridge->>Fridge: Check physical-item uniqueness Fridge->>FridgeStore: Append ItemAddedToFridge Fridge-->>Measure: ItemAddedToFridge Fridge-->>Gateway: Created FridgeItem Gateway-->>Web: 201 Created Web-->>Consumer: Show item in Fridge

Only scanId comes from the client. The Fridge obtains trusted GTIN, serial, expiry and display data from passport-service.