Simplified Development Description¶

This section explains the completed PackyTrace implementation tasks without assuming knowledge of the technologies involved.

Every task is explained twice:

1. Like you're 5 uses a simple real-world analogy.
2. Normal explanation describes what the software actually does.

Each explanation also introduces the main technologies used in that task.

The Big Picture¶

Like you're 5¶

PackyTrace is like a large shop with several specialist rooms:

• one room knows about products;
• one room will calculate personal health advice;
• one room will manage the fridge;
• one room manages people and consent;
• a receptionist sends every request to the correct room.

We first built one complete path through the building: scan a product, find it, save the scan, and show it on the website. We then made barcode links realistic, improved the website, and connected secure accounts, login, and consent.

Normal explanation¶

PackyTrace is made of independently deployed services. The completed work has created:

• a real product-scan path through the API gateway and passport service;
• PostgreSQL persistence and Kafka event publishing;
• a reusable GS1 Digital Link parser for real barcode URLs;
• a scan-first SvelteKit web application that uses the real API by default;
• Keycloak-backed account registration, login, logout, and real web authentication;
• protected account routes and an append-only health-profile consent system.

The personalized verdict and fridge backend are not complete yet.

Completed Phases¶

• Bird's Eye Overview — how the target services communicate through HTTP, Kafka, Keycloak, and isolated database schemas.
• Phase 0: Walking Skeleton — the first real end-to-end scan.
• Phase J1: Anonymous Scan — realistic GS1 barcode links and the complete anonymous scan journey.
• Frontend Rework — a truthful, scan-first interface connected through ports and adapters.
• Phase J2: Identity, Sessions, and Consent — real account registration, authentication, and consent management.

Common Technology Words¶

Word	Simple meaning
API	A defined way for software components to ask each other for things.
API gateway	The single front door that routes requests to the correct service.
Service	A small application responsible for one area of the business.
PostgreSQL	The database where PackyTrace stores structured information.
Migration	A versioned instruction that creates or changes database structures.
Kafka	A message system that lets services announce facts to other services.
Event	A message saying that something happened, such as ProductScanned.
HTTP	The request-and-response protocol used by browsers and APIs.
JSON	A text format used to exchange structured data.
Docker Compose	A tool that starts and connects all local services.
Go	The programming language used by several backend services.
TypeScript	JavaScript with additional type checking.
SvelteKit	The framework used to build the PackyTrace web application.
Keycloak	The system that manages credentials, login sessions, and identity tokens.
JWT	A digitally signed token that proves the caller's identity.
Consent ledger	An append-only history of permission grants and revocations.