PackyTrace — SAP Project Report Structure

Software Architecture and Platforms, a.y. 2025–2026

Goal: one living, versioned document (in the repo, e.g. /docs) that demonstrably covers everything Assignments #01–#03 ask for, using PackyTrace instead of "Shipping on the Air." Each section below notes (a) which assignment requirement it satisfies and (b) which existing artifact you can reuse.

0. Introduction & Requirements Traceability

  • 0.1 Project vision — one page: what PackyTrace is (reuse POS v2, condensed).
  • 0.2 Why this case study — short note that PackyTrace replaces Shipping on the Air, with professor's agreement.
  • 0.3 Traceability matrix — a table: assignment requirement → report section → code location. Put this up front; it's the examiner's map and your insurance that nothing is missed.
  • 0.4 Versioning — the report is a living doc: version number, changelog table. (Assignment #01 explicitly asks for "living doc, versioned" — Git history + a CHANGELOG section satisfies it.)

PART I — Analysis, DDD & Microservices (Assignment #01)

1. Requirements

  • 1.1 Functional requirements — derive directly from your User Stories MVP v1 (reuse as-is; reference epics/stories by ID).
  • 1.2 Non-functional requirements / quality attributes — make these explicit and measurable, because Parts II–III build on them:
  • Performance: scan → result p95 < 3 s.
  • Availability / fault tolerance: passport still renders when a data source fails (your story 1.6 — this becomes the Circuit Breaker pattern later).
  • Privacy: health data never crosses the brand wall in identifiable form (GDPR).
  • Scalability: scan bursts (e.g. campaign on a popular product).
  • 1.3 Quality Attribute Scenarios (QAS) — write 3–4 in the canonical six-part form (source, stimulus, artifact, environment, response, response measure). Two of these get implemented via observability in Part II, so choose them now.

2. Strategic Design (DDD)

  • 2.1 Ubiquitous Language — reuse your existing domain glossary (Scan, Passport, Verdict, Fridge, Alert, Profile…).
  • 2.2 Subdomains — classify: core = personalization/verdict ("does this fit me" is your differentiator); supporting = passport assembly, fridge, brand analytics; generic = identity/auth, notifications.
  • 2.3 Bounded Contexts & Context Map — e.g. Product Passport, Consumer Profile & Personalization, Fridge, Brand Analytics, Identity. Show relationships (customer–supplier, conformist with external GS1/Open Food Facts, anticorruption layer toward external data sources — an ACL here is very natural and scores DDD points).

3. Tactical Design (DDD)

  • 3.1 Aggregates — ProductCatalogEntry, HealthProfile, Fridge (with FridgeItem), Account, Brand. State invariants (e.g. "the same physical item cannot be added to a Fridge twice").
  • 3.2 Entities & Value Objects — value objects: GS1DigitalLink (GTIN, lot, expiry), EcoScore, Verdict, AllergenSet.
  • 3.3 Domain Events — ProductScanned, ItemAddedToFridge, ItemConsumed, ItemDiscarded, ItemExpiring, ProfileUpdated. (Define them carefully — Event Sourcing and Kafka in Parts II–III reuse exactly these.)
  • 3.4 Domain services & repositories — verdict computation as a domain service.

4. Architecture

  • 4.1 Microservices decomposition — five bounded-context services: passport-service, personalization-service (including Verdict), fridge-service, identity-service, and brand-analytics-service; plus the api-gateway and consumer-side measurement-pipeline architectural components. Justify boundaries by context map, exclusive data ownership, privacy, and operational pressure. See Microservices Decomposition.
  • 4.2 C4 diagrams — Context, Container, plus one Component diagram for the core service.
  • 4.3 API design — REST endpoints per service; note which are public (via gateway) vs internal. See API Design.
  • 4.4 Key flows — sequence diagrams for: anonymous scan, personalized scan (profile + verdict), add-to-fridge. See Key Flows.

5. Prototype & Demo (Assignment #01 deliverable)

  • What's implemented, how to run it, link to the short demo video (scan → verdict → fridge is the demo arc).

PART II — Patterns, Deployment & Testing (Assignment #02)

6. API Gateway

  • Single entry point for the consumer web app and brand dashboard; routing, auth, rate limiting. Note the privacy role: the gateway is part of the "wall" (brand routes can only reach aggregate endpoints).

7. Observability Patterns

  • 7.1 Health Check API — /health per service (liveness/readiness), checked by the orchestrator.
  • 7.2 Application Metrics — Prometheus-style: scan latency histogram, verdict computation time, external-source failure counters, scans-per-product counter (which doubles as the brand dashboard's raw data — nice synergy to point out).

8. Event Sourcing — applied to one service

  • Recommended: fridge-service. It's the textbook fit: state = fold of ItemAdded / ItemConsumed / ItemDiscarded / ItemExpired events; the monthly waste summary (story 4.5) is simply a projection over the event log. You get auditability and the feature almost for free, and it's easy to explain in the report.

9. Two patterns of your choice — recommendations

  • CQRS on the analytics side: scan events are written by consumer-facing services; the brand dashboard is a separate read model built from them. Pairs naturally with Event Sourcing and with the privacy wall (the read model only ever contains aggregates).
  • Circuit Breaker in passport-service toward external data sources (Open Food Facts, eco-score provider): when a source is down, trip the breaker and serve the degraded passport — this directly implements your story 1.6, so the pattern is motivated by a requirement, not bolted on.
  • (Alternatives if you prefer: Saga — weak fit here; Service Discovery; BFF — defensible since you have two very different clients.)

10. Deployment with containers

  • Dockerfile per service, docker-compose.yml for the full system (services + DBs + Prometheus). Keep it reproducible: one command to run everything.

11. Testing strategy — one example per pyramid level

  • Unit: verdict logic (profile × product → Good/Careful/Avoid) — pure domain, fast, the best unit-test subject you have.
  • Integration: fridge-service against its event store, or passport-service against a stubbed Open Food Facts (also shows the breaker).
  • End-to-end: scan a known product through the gateway → assert the full passport + verdict JSON.

12. QAS via Observability — two concrete examples (explicit assignment requirement)

  • QAS-1 (Performance): stimulus = burst of N concurrent scans; response measure = p95 scan latency < 3 s — measured by the latency histogram from §7.2, shown on a dashboard/screenshot.
  • QAS-2 (Availability/fault tolerance): stimulus = eco-score source goes down; response = passport served degraded, error rate on the endpoint stays < X% — measured by health checks + failure counters + breaker-state metric.
  • For each: scenario table → which metric/health-check detects it → screenshot of the measurement.

PART III — Event-driven, Scaling, Agents (Assignment #03)

13. Event-driven re-engineering with Kafka (one service)

  • Recommended candidate: the consumer-side measurement pipeline. passport-service, personalization-service, fridge-service, and identity-service publish raw measurement facts. The pipeline aggregates them and publishes only minimum-group-size BrandMetricBatchPublished events to brand-analytics-service. Justify the choice: measurement is naturally asynchronous and the pipeline makes the privacy wall enforceable. Other services keep their architecture and only adapt at the boundary.
  • Cover: topic design, partitioning key (e.g. GTIN), consumer groups, delivery semantics, schema of events (reuse §3.3).

14. SLOs, SLIs & Kubernetes

  • SLO-1: 95% of scan requests complete in < 3 s over 30 days. SLI: p95 latency at the gateway (Prometheus histogram).
  • SLO-2: 99.5% availability of the passport endpoint. SLI: success ratio = 2xx/(total) from gateway metrics.
  • Show the SLI measurement implementation (queries/dashboards) — the assignment says "extending the implementation so as to measure the SLIs."
  • Kubernetes deployment: manifests (Deployments, Services, ConfigMaps), liveness/readiness probes wired to §7.1 health checks, optionally an HPA on passport-service driven by CPU or scan rate — which closes the loop with SLO-1.

15. (Optional) Agent-based architecture

  • The drone maps poorly, but you have a natural agent: the personal food assistant. Model it BDI-style: beliefs = profile + fridge contents + expiry dates; desires = user's goal (adherence, zero waste); intentions = generated suggestions ("use the yogurt today; it fits your protein target"). A small prototype agent that observes fridge events (from Kafka!) and proactively emits suggestions would tie Parts I–III together elegantly. Do it only if time allows — it's optional.

Appendices

  • A. Glossary / Ubiquitous Language (full)
  • B. ADRs (Architecture Decision Records) — 5–8 short ones: "why microservices," "why event sourcing on fridge," "why Kafka for scans," "why CQRS + Circuit Breaker as free-choice patterns," "why K8s layout X." Cheap to write, very high signal for examiners.
  • C. How to run (compose & K8s), repo map
  • D. Changelog of this document

Suggested repo layout

packytrace/
├── docs/                 # this report (split per part or single file)
│   ├── report.md
│   └── adr/
├── services/
│   ├── api-gateway/
│   ├── passport-service/
│   ├── personalization-service/
│   ├── fridge-service/      # event-sourced
│   ├── identity-service/
│   ├── measurement-pipeline/ # raw facts -> privacy-safe aggregates
│   └── brand-analytics-service/ # CQRS aggregate read model
├── deployment/
│   ├── docker-compose.yml
│   └── k8s/
├── tests/                # or per-service, with e2e/ at top level
└── README.md             # links to report, demo video, run instructions