# sandangt/icecream architecture

> Architecture diagram of the GitHub repository sandangt/icecream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sandangt/icecream
- Repository: https://github.com/sandangt/icecream

## Overview

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: [`icecream-system/consul`](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/consul) (Consul), [`icecream-system/echo`](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/echo) (Echo), [`icecream-system/codex`](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/codex) (Codex), [`icecream-system/dev-composes/kafka`](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/kafka) (Kafka)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "User surfaces"
  storefront["Storefront UI<br/>Next.js app"]
  horus["Horus<br/>Backoffice app"]
  frontend_client["Storefront repos<br/>API client layer"]
end

subgraph "Core services"
  consul["Consul<br/>Transactional core"]
  conflux["Conflux<br/>Read-model service"]
  echo["Echo<br/>Notification service"]
  memoir["Memoir<br/>Audit service"]
  chronos["Chronos<br/>Background jobs"]
  codex["Codex<br/>Config service"]
  consul_services["Consul domain<br/>HTTP service layer"]
  echo_delivery["Echo delivery<br/>Realtime + email"]
  conflux_pipeline["Conflux pipeline<br/>Enrichment flow"]
end

subgraph "Shared platform"
  fundamentum["Fundamentum<br/>Shared library"]
  identity["Identity<br/>Keycloak IDP"]
  devcomposes["Dev stack<br/>Compose platform"]
  postgresql[("PostgreSQL<br/>Transactional DB")]
  mongodb[("MongoDB<br/>Document store")]
  redis[("Redis<br/>Cache")]
  minio[("MinIO<br/>Object storage")]
  kafka["Kafka<br/>Event bus"]
  debezium["Debezium<br/>CDC pipeline"]
  otel["OTel stack<br/>Observability"]
end

storefront -->|"uses"| frontend_client
frontend_client -->|"HTTP"| consul
frontend_client -->|"notifications"| echo
frontend_client -->|"auth"| identity
horus -->|"operates on"| consul
consul -->|"persists"| postgresql
consul -->|"caches"| redis
consul -->|"stores files"| minio
consul -->|"auth calls"| identity
consul -->|"emits async"| kafka
consul -->|"audit"| memoir
consul -->|"notifications"| echo
consul -->|"source data"| conflux
conflux -->|"publishes"| kafka
conflux -->|"RSocket read"| consul
echo -->|"persists"| mongodb
echo -->|"consumes"| kafka
echo -->|"auth"| identity
memoir -->|"persists"| postgresql
memoir -->|"consumes"| kafka
chronos -->|"storage work"| minio
chronos -->|"consumes"| kafka
debezium -->|"captures changes"| postgresql
debezium -->|"streams"| kafka
debezium -->|"observed by"| otel
otel -->|"instrumentation"| consul
otel -->|"instrumentation"| echo
otel -->|"instrumentation"| conflux
otel -->|"instrumentation"| memoir
identity -->|"login"| storefront
identity -->|"login"| horus
codex -->|"configures"| consul
codex -->|"configures"| conflux
codex -->|"configures"| echo
codex -->|"configures"| memoir
codex -->|"configures"| chronos

click storefront "https://github.com/sandangt/icecream/tree/master/icecream-ui/storefront"
click horus "https://github.com/sandangt/icecream/tree/master/icecream-system/horus"
click consul "https://github.com/sandangt/icecream/tree/master/icecream-system/consul"
click conflux "https://github.com/sandangt/icecream/tree/master/icecream-system/conflux"
click echo "https://github.com/sandangt/icecream/tree/master/icecream-system/echo"
click memoir "https://github.com/sandangt/icecream/tree/master/icecream-system/memoir"
click chronos "https://github.com/sandangt/icecream/tree/master/icecream-system/chronos"
click codex "https://github.com/sandangt/icecream/tree/master/icecream-system/codex"
click fundamentum "https://github.com/sandangt/icecream/tree/master/icecream-system/fundamentum"
click identity "https://github.com/sandangt/icecream/tree/master/icecream-system/identity"
click devcomposes "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes"
click postgresql "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/postgresql"
click mongodb "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/mongodb"
click redis "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes"
click minio "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/minio"
click kafka "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/kafka"
click debezium "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/debezium"
click otel "https://github.com/sandangt/icecream/tree/master/icecream-system/dev-composes/otel-collector"
click frontend_client "https://github.com/sandangt/icecream/tree/master/icecream-ui/storefront/src/repositories"
click consul_services "https://github.com/sandangt/icecream/tree/master/icecream-system/consul/src/main/java/sanlab/icecream/consul"
click echo_delivery "https://github.com/sandangt/icecream/tree/master/icecream-system/echo/src/main/java/sanlab/icecream/echo"
click conflux_pipeline "https://github.com/sandangt/icecream/tree/master/icecream-system/conflux/src/main/java/sanlab/icecream/conflux"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class storefront,horus,frontend_client toneBlue
class consul,conflux,echo,memoir,chronos,codex,consul_services,echo_delivery,conflux_pipeline toneAmber
class fundamentum,identity,devcomposes,postgresql,mongodb,redis,minio,kafka,debezium,otel toneMint
```

## Components

### User surfaces

Customer and staff-facing applications

- [Storefront UI](https://github.com/sandangt/icecream/tree/HEAD/icecream-ui/storefront): Next.js app · Public customer storefront for shopping, checkout, profile, and order flows. · `icecream-ui/storefront`
- [Horus](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/horus): Backoffice app · Internal admin application for operational workflows and product/stock management. · `icecream-system/horus`
- [Storefront repos](https://github.com/sandangt/icecream/tree/HEAD/icecream-ui/storefront/src/repositories): API client layer · 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](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/consul): Transactional core · Source of truth for commerce data: customers, carts, orders, products, stock, feedback, and payment webhooks. · `icecream-system/consul`
- [Conflux](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/conflux): Read-model service · Consumes source data from Consul and produces enriched product read models. · `icecream-system/conflux`
- [Echo](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/echo): Notification service · Handles WebSocket bell notifications, email delivery, and notification persistence. · `icecream-system/echo`
- [Memoir](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/memoir): Audit service · Immutable audit trail boundary for audit log capture and internal access. · `icecream-system/memoir`
- [Chronos](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/chronos): Background jobs · Executes deferred work, consumers, and storage/image-related background processing. · `icecream-system/chronos`
- [Codex](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/codex): Config service · Centralized configuration module for shared environment and service-specific settings. · `icecream-system/codex`
- [Consul domain](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/consul/src/main/java/sanlab/icecream/consul): HTTP service layer · Controllers, services, repositories, RSocket endpoints, security, and persistence for core commerce. · `icecream-system/consul/src/main/java/sanlab/icecream/consul`
- [Echo delivery](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/echo/src/main/java/sanlab/icecream/echo): Realtime + email · WebSocket notification delivery, email templates, and notification consumers. · `icecream-system/echo/src/main/java/sanlab/icecream/echo`
- [Conflux pipeline](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/conflux/src/main/java/sanlab/icecream/conflux): Enrichment flow · 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](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/fundamentum): Shared library · Cross-service contracts, DTOs, enums, mappers, utilities, and error models. · `icecream-system/fundamentum`
- [Identity](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/identity): Keycloak IDP · Central authentication provider with realm import data and custom login theme. · `icecream-system/identity`
- [Dev stack](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes): Compose platform · Local development infrastructure for databases, brokers, CDC, storage, and telemetry. · `icecream-system/dev-composes`
- [PostgreSQL](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/postgresql): Transactional DB · System-of-record storage for core services and audit data. · `icecream-system/dev-composes/postgresql`
- [MongoDB](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/mongodb): Document store · Notification persistence backend for Echo. · `icecream-system/dev-composes/mongodb`
- [Redis](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes): Cache · Hot-data and caching layer used by Consul. · `icecream-system/dev-composes`
- [MinIO](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/minio): Object storage · Binary and image storage used by core and background workflows. · `icecream-system/dev-composes/minio`
- [Kafka](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/kafka): Event bus · Async messaging backbone used by service queues and CDC pipeline. · `icecream-system/dev-composes/kafka`
- [Debezium](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/debezium): CDC pipeline · Captures PostgreSQL changes and feeds downstream projections/search. · `icecream-system/dev-composes/debezium`
- [OTel stack](https://github.com/sandangt/icecream/tree/HEAD/icecream-system/dev-composes/otel-collector): Observability · OpenTelemetry collector plus metrics, logs, traces, and dashboarding. · `icecream-system/dev-composes/otel-collector`

## Connections

- 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.
