Architecture

This section turns the canonical domain model into the implemented service architecture. The services are independently deployed; this superseded the early modular-monolith direction recorded in the ADR history.

Architecture reference

  1. Microservices and patterns: decomposition, ownership, API Gateway, CQRS and circuit breaker.
  2. Component & connector views: the runtime views of the system. The public edge, the internal call-return collaboration with its timeouts and fallbacks, the schema-per-service data isolation, and the event topics with the privacy wall.
  3. Software structure: the repository, the technology stack, the inward dependency rule with its ports and adapters, the fitness functions that enforce it and where to find them, and a summary of the DevOps pipeline.
  4. OpenAPI: interactive public and internal HTTP contracts for every deployed service.
  5. Key flows: anonymous scan, personalized scan and add-to-Fridge sequences.
  6. Event Sourcing: the Fridge and Shopping List streams, replay, transactional projections, integration-event boundaries and the measurement pipeline.
  7. Service communication: when the system uses REST and when it uses Kafka facts.
  8. Observability: implemented telemetry and known operational gaps; Observability Verification owns QAS evidence and dashboards.
  9. SLOs & SLIs: the two measured service levels on the scan journey.
  10. Testing strategy: the implemented test pyramid and delivery pipeline.

Each service's HTTP surface is described by its machine-readable 'services//openapi.yaml'.

Architecture in one view

The architecture rests on a small set of connected decisions:

  • The seven DDD bounded contexts become seven deployable services. The API Gateway is the application edge and is not a bounded context; Measurement & Anonymization is a bounded context implemented by measurement-pipeline.
  • Each data-bearing service owns a GRANT-restricted Postgres schema. Other services use internal APIs, stable IDs or versioned events instead of foreign tables.
  • Keycloak issues tokens; the gateway validates them, removes untrusted identity headers and forwards verified account or Brand scope.
  • Raw consumer facts stay behind the privacy wall. Only minimum-group-size BrandMetricBatchPublished aggregates enter Brand Analytics.
  • Go cores and TypeScript domain/application layers stay independent from adapters and configuration; composition roots perform concrete wiring.
  • Compose, Kubernetes, Prometheus and Grafana provide deployment, health, and service-level mechanisms with the limitations recorded in their operating guides.