Backend Architecture — Architecture Documentation

Backend Architecture

Four Spring Boot / JHipster services: gateway (auth), store and commerce (stateless proxies), and the catalog core that owns all business logic.

Diagram v1.4 · Updated 04 Aug 2026, 08:10 GST— Controller → service → repository layering and scheduler inventory documented per service.

100%

Rendering diagram…

Scroll to zoom · drag to pan

1 · Step-by-step workflow

01

Request arrives at an edge service

Store or commerce receives the proxied /api/v1/** call with the relayed Bearer JWT.

02

Edge validates and rewrites

Each service validates the JWT as an OAuth2 resource server using the shared HMAC secret.
Proxy resources rewrite /api/v1/X → /internal/v1/X and attach the internal API key.

03

Core controller receives the internal call

InternalStorefrontResource, InternalAccountOrderResource, InternalAdminStoreResource, InternalAdminImportResource, InternalOrderReturnResource and InternalStorageUploadResource handle the surface.

04

Domain service executes

Each domain service is paired with an XxxQueryService using JPA Specification/Criteria search.
MapStruct maps entities to DTOs.

05

Repository persists

Spring Data JPA over the miniandmore database; Liquibase owns the schema.
Redisson caches hot lookups.

06

Schedulers reconcile in the background

Ledgerly order retry, order tracking pull and inventory pull run on fixed delays.
Inventory reservation release runs on its own fixed delay.

2 · Additional details

01

Service responsibilities

Gateway — AuthenticateController, AccountResource, UserResource/AuthorityResource, PublicUserResource, GatewayResource, JwtTokenService, Google OAuth2 handlers, JWTRelayGatewayFilterFactory.
Store — CatalogCoreClient, StoreCatalogProxyResource, AdminImportProxyResource, AdminUploadProxyResource.
Backend — all internal resources plus LedgerlyAdminResource under /api/v1/admin/ledgerly/**.

02

Service-to-service communication

Gateway → store/commerce over Consul lb:// with default-filters [JWTRelay], 5s connect / 120s response timeouts.
Store/commerce → backend over a fixed CATALOG_BASE_URL (default http://127.0.0.1:8084) using Spring RestClient — not Feign.

03

Background services

LedgerlySyncScheduler.retryFailedOrderSync — LEDGERLY_ORDER_RETRY_MS, default 5 min.
LedgerlySyncScheduler.pullOpenOrderTracking — LEDGERLY_ORDER_TRACKING_MS, default 1 hr.
LedgerlyInventoryPullScheduler.pullInventory — LEDGERLY_INVENTORY_PULL_MS.
All Ledgerly schedulers are @ConditionalOnProperty gated and off in dev without LEDGERLY_API_TOKEN.

04

Authentication & authorization

JWT issued only by the gateway; HMAC NimbusJwtDecoder on the core.
AuthoritiesConstants defines ROLE_ADMIN / ROLE_USER / ROLE_ANONYMOUS.
SecurityMetersService exposes Micrometer counters for JWT decode failures.

3 · Advantages & usage

Advantage

Business rules stay out of controllers, so they are unit-testable.
New endpoints reuse existing services instead of re-querying.

Usage

Every internal resource delegates to a domain service and its paired query service.

4 · Phase 2 additions

01

Version alignment

Bring the gateway from Spring Boot 3.5 / JHipster 8.12 up to 4.0 / 9.0 to match the other services.

02

Explicit authorisation on upload

Add @PreAuthorize to InternalStorageUploadResource instead of relying on the store-level admin rule.

03

Outbox-style integration delivery

Move Ledgerly pushes behind a durable outbox with retries and dead-lettering.