Service Communication¶
PackyTrace uses two communication mechanisms:
- Synchronous REST when the caller needs an immediate response.
- Asynchronous events when a service publishes an integration fact for other services to process.
Services never communicate through another service's database schema.
Synchronous REST¶
Clients call only the api-gateway. Keycloak performs authentication and issues tokens; the gateway validates token signatures and claims when present or required, adds trusted identity headers, and forwards the request to the service that owns the endpoint.
Browser -> api-gateway -> owning service -> its own Postgres schema
Some backend workflows also use private REST endpoints. For example, Fridge and Shopping List ask Passport for trusted product data, while Passport asks Personalization for a health verdict. These internal endpoints are not exposed to clients.
Each service's public and internal paths are listed in its own
'services/
Asynchronous Events¶
Services publish versioned integration facts such as ProductScanned or ItemDiscarded to a broker. Consumers process them independently, so the publisher does not wait for their work to finish.
Producing service -> Kafka-compatible topic -> consuming service
Event payloads use the versioned JSON Schemas in contracts/. They contain facts and reason codes, not database models or localized text. Brand analytics receives only privacy-safe aggregates from the Measurement Pipeline.
The events themselves, the contracts, the services that store their data as events, and the measurement pipeline that consumes them are all described on one page: Event Sourcing.
Local and deployed environments¶
| Concern | Local development | AWS deployment |
|---|---|---|
| Browser entry point | Web apps on localhost:5173 and localhost:5174 call the gateway on localhost:8080; CORS allows these split origins. | Caddy serves the apps over HTTPS and proxies API requests to the gateway on the same origin. |
| Service addressing | Containers use Docker DNS names such as passport-service:8081. | Containers use the same Docker DNS mechanism inside the private Compose network. |
| Event broker | Apache Kafka at kafka:9092. | Redpanda at redpanda:9092, using the same Kafka protocol, topics, and contracts. |
| Public exposure | Development ports expose the gateway and selected infrastructure for local tooling. | Only Caddy is public; services, Postgres, Redpanda, and Keycloak remain private. |
localhost always means the current machine or container. A container therefore reaches another container by its Compose service name, not by localhost.
This table is only an orientation summary. The deployment section owns the current environment configuration. The communication rules apply in every environment: deployment changes addresses and edge routing, not service boundaries.