How sandangt/icecream works
This repository is a monorepo for a distributed e-commerce system. The architecture is split into multiple independently deployable Java services, two user-facing applications, shared contracts/utilities, and a local development infrastructure stack.
At a high level, the system separates:
• transactional write paths
• asynchronous side effects
• read-model/enrichment paths
• internal backoffice operations
• identity/authentication
• observability and local platform services
Main application surfaces
Storefront UI
icecream-ui/storefront is the public customer-facing frontend, built with Next.js/React.
It is the primary entry point for shoppers and interacts with:
• the core business API in consul
• authentication via the identity provider
• notification/session-related features through echo
• product and order views that depend on enriched/read models
The frontend includes:
• cart, checkout, product detail, profile, order confirmation pages
• auth integration through NextAuth-style auth routing
• repository wrappers for backend APIs in src/repositories/*
• client-side state/hooks for cart, profile, and notifications
Backoffice UI
icecream-system/horus is the internal admin application.
It is a separate application with:
• a Java backend
• a frontend module under src/main/frontend
• a product/stock focus in its local domain model
It appears to support operational workflows such as product management and payment webhook handling, rather than customer shopping flows.
Core backend services
Consul — transactional core
icecream-system/consul is the main business service and the source of truth for core commerce data.
Its responsibilities include:
• customers
• carts
• orders
• products
• categories
• images
• stock
• feedback
• payment webhook handling
• security and API-key enforcement
This service is the central transactional boundary. The package layout makes the layering explicit:
• controllers handle HTTP input
• services contain business logic
• repositories abstract persistence/integration
• mappers convert between entities and DTOs/view models
Consul integrates with several external/internal systems:
• PostgreSQL for transactional persistence
• Redis for caching/hot data
• MinIO for file/object storage
• Keycloak/identity service for auth-related calls
• payment integration through REST client abstractions
• RabbitMQ/Kafka-style async queues through queue repositories
• RSocket internal endpoints for service-to-service data exchange
Consul also contains:
• internal RSocket controller for product enrichment data
• queue repositories for audit logging, notifications, images, and “hello mate” messages
• Elasticsearch-oriented entities/repositories for searchable projections
This is the service where writes originate and where domain events are effectively emitted to the rest of the system.
Conflux — enrichment / read-model service
icecream-system/conflux is the enrichment and consumption layer.
Its structure shows that it:
• consumes source data for products, categories, and images
• maps “source” models into “enriched” models
• publishes or sinks enriched product data into a queue
It depends on Consul through RSocket client repositories:
• product source access
• category source access
• image source access
Conflux is the CQRS/read-side-oriented service in the system. It does not own the authoritative transactional data; instead, it pulls source data from Consul and shapes it into read-optimized models for downstream consumers.
Chronos — scheduled/background task service
icecream-system/chronos handles time-based and deferred work.
The visible responsibilities are:
• consumers for background queue messages
• storage access through MinIO
• “image” processing/handling workflows
• generic delayed task execution patterns
Chronos is the place for work that should not run inline with user requests, such as retries, expirations, scheduled jobs, or post-processing of stored files.
Echo — asynchronous notifications service
icecream-system/echo is the notification subsystem.
It has a mix of:
• WebSocket support
• notification consumers
• email delivery templates
• MongoDB-backed notification storage
• security and interceptors for real-time connections
Echo is responsible for outward notification channels:
• bell notifications to clients
• email notifications
• processing of order-related and generic “hello mate” messages
This service is deliberately decoupled from core transaction processing so notification failures do not block business writes.
Memoir — audit log service
icecream-system/memoir is the immutable audit trail service.
It:
• receives audit log data
• stores audit entries in PostgreSQL
• exposes an internal RSocket controller for writes or queries
• consumes audit-related events
Memoir is a compliance/history boundary rather than a business workflow service. It captures what happened, independent of operational state in Consul.
Codex — configuration service
icecream-system/codex is the central configuration module.
The repository tree does not show much runtime surface, but the module exists as a dedicated service for centralized configuration and environment-specific overrides. In the architecture, this acts as shared runtime configuration plumbing for the other services.
Shared library
Fundamentum
icecream-system/fundamentum is the shared internal library used across services.
It contains:
• common DTOs and contract models
• enums/constants
• utility classes
• base mappers
• error models
• shared request/response contracts
This library is a cross-cutting boundary for consistent modeling and helper functions. It reduces duplication across the service modules, especially around domain enums, request/response shapes, and utility logic.
Identity and authentication
Keycloak-based IDP
icecream-system/identity contains Keycloak import data and a custom theme.
This is the centralized identity provider for the whole system:
• realm export JSON for bootstrap
• custom login/register theme resources
Authentication is token-based, and both frontend applications integrate with the identity layer. The backoffice and storefront do not own authentication themselves; they delegate to the IDP.
Data storage and persistence boundaries
The system intentionally avoids a single shared database. Each service owns its own storage and domain boundary.
PostgreSQL
Used for the core transactional services:
• Consul
• Horus
• Memoir
• likely other supporting services depending on their runtime config
This is the system of record for business data and audit data.
MongoDB
Used in Echo for notification message persistence.
This fits the notification domain, which is not the same access pattern as the transactional core.
Redis
Used by Consul for caching and hot reads.
MinIO
Used for object storage:
• images
• large binary assets
• file handling workflows
Chronos and Consul both have storage abstractions around MinIO.
Elasticsearch
Used for search-oriented read models.
The repository tree shows Elasticsearch-related entities and index settings in Consul, and the dev compose stack includes Debezium connectors that push data into Elasticsearch. This indicates search is fed by CDC/projection pipelines rather than direct writes from the application layer.
Messaging and eventing
The system uses multiple asynchronous patterns:
RabbitMQ / queue-based messaging
Queue repositories exist in Consul, Conflux, Echo, Chronos, and Memoir. These represent asynchronous domain workflows such as:
• notifications
• audit logging
• image handling
• enrichment
Kafka + Debezium CDC
The local compose setup includes:
• Kafka
• Debezium Postgres source connector
• Elasticsearch sink connector
This is the CDC backbone for propagating changes out of the transactional database into downstream read models/search infrastructure.
The important architecture point is that Consul remains the source of truth, and downstream systems are fed by events/change capture instead of direct database coupling.
RSocket
RSocket is used for internal service-to-service data access and event-style interactions.
Visible RSocket relationships include:
• Consul exposing source data for Conflux
• Consul and Memoir internal RSocket controllers/repositories
• service-specific RSocket configuration classes
This creates a separate internal communication plane distinct from HTTP REST.
WebSocket
Echo exposes WebSocket-based notification delivery for live UI updates.
This is the real-time push channel to clients for bell/notification scenarios.
External integrations
The repository shows concrete integration points that matter architecturally:
• payment provider integration through REST clients and webhook controllers
• Keycloak for identity and token auth
• MinIO for object storage
• Grafana stack for observability
• Elastic-style search projections
• message broker infrastructure for async workflows
Observability stack
The development infrastructure includes a full telemetry pipeline:
• OpenTelemetry Java agent attached to services
• OpenTelemetry Collector as the ingest hub
• Prometheus + Mimir for metrics
• Loki for logs
• Tempo for traces
• Grafana for visualization
• MinIO for telemetry object storage needs
This means the services are instrumented as a distributed system, not as isolated apps. The observability pipeline is a first-class part of the architecture.
Local infrastructure / compose environment
icecream-system/dev-composes defines the local runtime stack, including:
• PostgreSQL
• MongoDB
• Redis
• MinIO
• Kafka
• Debezium
• OTel collector
• Prometheus
• Mimir
• Loki
• Tempo
• Stripe-related local services
• supporting init scripts for topics, buckets, databases, and connectors
This compose layer is important because it reflects the runtime boundaries and dependencies of the system.
Main data flow
A typical customer/business flow looks like this:
1. The user authenticates through Keycloak.
2. The storefront calls Consul for product, cart, checkout, and order actions.
3. Consul persists authoritative data in PostgreSQL and may cache selected data in Redis.
4. Consul stores binaries in MinIO when needed, such as images.
5. Consul emits asynchronous side effects through queues and internal channels.
6. Conflux consumes/source-fetches data from Consul and builds enriched read models.
7. Debezium captures DB changes and feeds downstream search/indexing infrastructure.
8. Echo consumes notification-related work and delivers email/WebSocket bell notifications.
9. Memoir records audit events for traceability/compliance.
10. Chronos handles deferred/background tasks and storage-related workflows.
11. Horus provides internal operational access for staff workflows.
Diagram boundaries to preserve
If you are drawing the architecture, the most important boundaries are:
• public storefront versus internal backoffice
• transactional core versus read/enrichment services
• synchronous HTTP/RSocket calls versus asynchronous queue/event flows
• service-owned databases versus CDC-fed projections
• authentication/identity as a shared platform service
• observability as a separate cross-cutting platform layer
The overall pattern is a distributed, event-assisted e-commerce platform with strong domain separation rather than a single monolith.
Main entry points: consul Consul · echo Echo · codex Codex · kafka Kafka
Components 22
User surfaces
Customer and staff-facing applications
- Storefront UI · Public customer storefront for shopping, checkout, profile, and order flows.
icecream-ui/storefront - Horus · Internal admin application for operational workflows and product/stock management.
icecream-system/horus - Storefront repos · Repository wrappers and hooks that call Consul, Echo, and Identity from the UI.
icecream-ui/storefront/src/repositories
Core services
Transactional, enrichment, notification, audit, scheduling, and config services
- Consul · Source of truth for commerce data: customers, carts, orders, products, stock, feedback, and payment webhooks.
icecream-system/consul - Conflux · Consumes source data from Consul and produces enriched product read models.
icecream-system/conflux - Echo · Handles WebSocket bell notifications, email delivery, and notification persistence.
icecream-system/echo - Memoir · Immutable audit trail boundary for audit log capture and internal access.
icecream-system/memoir - Chronos · Executes deferred work, consumers, and storage/image-related background processing.
icecream-system/chronos - Codex · Centralized configuration module for shared environment and service-specific settings.
icecream-system/codex - Consul domain · Controllers, services, repositories, RSocket endpoints, security, and persistence for core commerce.
icecream-system/consul/src/main/java/sanlab/icecream/consul - Echo delivery · WebSocket notification delivery, email templates, and notification consumers.
icecream-system/echo/src/main/java/sanlab/icecream/echo - Conflux pipeline · RSocket source reads, mapping, and queue sink for enriched product data.
icecream-system/conflux/src/main/java/sanlab/icecream/conflux
Shared platform
Common contracts, identity, observability, and local infrastructure
- Fundamentum · Cross-service contracts, DTOs, enums, mappers, utilities, and error models.
icecream-system/fundamentum - Identity · Central authentication provider with realm import data and custom login theme.
icecream-system/identity - Dev stack · Local development infrastructure for databases, brokers, CDC, storage, and telemetry.
icecream-system/dev-composes - PostgreSQL · System-of-record storage for core services and audit data.
icecream-system/dev-composes/postgresql - MongoDB · Notification persistence backend for Echo.
icecream-system/dev-composes/mongodb - Redis · Hot-data and caching layer used by Consul.
icecream-system/dev-composes - MinIO · Binary and image storage used by core and background workflows.
icecream-system/dev-composes/minio - Kafka · Async messaging backbone used by service queues and CDC pipeline.
icecream-system/dev-composes/kafka - Debezium · Captures PostgreSQL changes and feeds downstream projections/search.
icecream-system/dev-composes/debezium - OTel stack · OpenTelemetry collector plus metrics, logs, traces, and dashboarding.
icecream-system/dev-composes/otel-collector
Connections 36
- Storefront UI → Storefront repos: uses · UI pages and hooks delegate backend calls to repository wrappers.
- Storefront repos → Consul: HTTP · Storefront reads and writes core commerce data through Consul APIs.
- Storefront repos → Echo: notifications · Storefront consumes bell notification features from Echo.
- Storefront repos → Identity: auth · Storefront authentication routes and session handling integrate with the IDP.
- Horus → Consul: operates on · Backoffice workflows manage products, stock, and webhook-related actions.
- Consul → PostgreSQL: persists · Consul owns the authoritative transactional database.
- Consul → Redis: caches · Consul uses Redis for hot reads and caching.
- Consul → MinIO: stores files · Consul writes object assets such as images to MinIO.
- Consul → Identity: auth calls · Consul integrates with the identity provider for token and user-related operations.
- Consul → Kafka: emits async · Core workflows fan out side effects through queue/event channels.
- Consul → Memoir: audit · Consul sends audit log data to the audit service.
- Consul → Echo: notifications · Order and message events flow to Echo for delivery.
- Consul → Conflux: source data · Consul exposes product, category, and image data for enrichment.
- Conflux → Kafka: publishes · Enriched product data is pushed downstream via queue sink.
- Conflux → Consul: RSocket read · Conflux reads source models from Consul through internal RSocket repositories.
- Echo → MongoDB: persists · Notification messages are stored in MongoDB.
- Echo → Kafka: consumes · Echo processes notification and order-related queue messages.
- Echo → Identity: auth · Real-time access is secured through the shared identity layer.
- Memoir → PostgreSQL: persists · Audit entries are stored in PostgreSQL.
- Memoir → Kafka: consumes · Audit service consumes audit-related events.
- Chronos → MinIO: storage work · Background jobs handle image and file processing around object storage.
- Chronos → Kafka: consumes · Chronos executes deferred queue-backed work.
- Debezium → PostgreSQL: captures changes · CDC reads the transactional database for downstream projections.
- Debezium → Kafka: streams · Database changes are streamed through Kafka.
- Debezium → OTel stack: observed by · CDC infrastructure participates in the local telemetry stack.
- OTel stack → Consul: instrumentation · Services export traces, metrics, and logs into the observability pipeline.
- OTel stack → Echo: instrumentation · Services export traces, metrics, and logs into the observability pipeline.
- OTel stack → Conflux: instrumentation · Services export traces, metrics, and logs into the observability pipeline.
- OTel stack → Memoir: instrumentation · Services export traces, metrics, and logs into the observability pipeline.
- Identity → Storefront UI: login · Identity is the centralized authentication entry point for customer sessions.
- Identity → Horus: login · Identity backs internal staff authentication as well.
- Codex → Consul: configures · Central configuration feeds Consul runtime settings.
- Codex → Conflux: configures · Central configuration feeds Conflux runtime settings.
- Codex → Echo: configures · Central configuration feeds Echo runtime settings.
- Codex → Memoir: configures · Central configuration feeds Memoir runtime settings.
- Codex → Chronos: configures · Central configuration feeds Chronos runtime settings.