How stpfeffer/merkana works
Project type and purpose
• This is a Java 21+ Spring Boot “modular monolith” e-commerce backend (“Merkana”), organized as a multi-module Maven project.
• It powers core e-commerce domains (catalog, cart, order, payment, promotion, etc.), exposes GraphQL/REST APIs, and integrates with data stores (PostgreSQL, MongoDB, Redis, Elasticsearch) and external services (payment gateways, email, shipping, webhooks).
File structure to infer architectural boundaries
• Top-level pom.xml aggregates all modules/merkana-* projects.
• modules/merkana-web contains the Spring Boot application entrypoint, API controllers (GraphQL + REST), interceptors, and application.yml profiles.
• Domain modules (merkana-cart, -catalog, -order, -product, -promotion, etc.) encapsulate business logic and domain objects (BOs, events, enums).
• Infrastructure/support modules (merkana-cache, -redis, -logging, -analytics, -audit, -mail, -notification, -search, -sandbox) provide cross-cutting concerns.
• merkana-core provides shared abstractions (context, exceptions, filters, DTOs, utilities).
README for additional insights
• The architecture follows Clean Architecture and modular monolith patterns:
• Clear separation between API layer, application/services layer, domain, and infrastructure.
• Centralized BOM for dependency management.
• Docker Compose orchestrates Postgres, Redis, MongoDB, Elasticsearch, Prometheus, Grafana.
• Observability: Prometheus metrics, Grafana dashboards, Qodana for static analysis.
a. Main components / layers
• CLIENT / CONSUMER (UI, third-party integrators)
• API GATEWAY / ENTRY POINT (modules/merkana-web: REST controllers, GraphQL resolvers, interceptor chain)
• APPLICATION / SERVICE LAYER (service beans orchestrating domain modules)
• DOMAIN MODULES (cart, catalog, order, product, payment, promotion, user, review, shipment, etc.)
• INFRASTRUCTURE MODULES (cache, redis, mail, notification, search, analytics, audit, logging)
• SHARED CORE (context, exceptions, filters, DTOs)
• DATA STORES (PostgreSQL, MongoDB, Redis, Elasticsearch)
• EXTERNAL SERVICES (payment gateway, email SMTP, shipping provider, webhook targets)
• OBSERVABILITY STACK (Prometheus, Grafana)
b. Relationships & data flows
1. CLIENT → API GATEWAY (“merkana-web”) → Authentication (JWT)
2. API Gateway → appropriate SERVICE bean → DOMAIN MODULE logic
3. DOMAIN MODULE → Repository / DAO → DATA STORE
4. DOMAIN EVENTS published (within modules or to Kafka/event bus if extended)
5. Infrastructure modules (cache, redis) interposed for read-cache or session data
6. Notifications/emails triggered via mail/notification modules → EXTERNAL SERVICES
7. Periodic analytics jobs → analytics module → Elasticsearch / MongoDB
8. Observability: Prometheus exporter beans → Prometheus → Grafana
c. Architectural patterns & design principles
• Modular Monolith / Clean Architecture: group by business capability, decouple layers.
• Dependency Injection via Spring
• Centralized BOM enforces consistent versions.
• Environment-driven configuration (application-*.yml, .env files).
• Potential for microservice extraction at module boundaries.
d. Key technologies
• Java 21+, Spring Boot 3.x, Spring Data, Spring Security (JWT)
• GraphQL (module: merkana-graphql) and REST (module: merkana-rest) endpoints
• Maven multi-module build
• PostgreSQL (primary RDBMS), MongoDB (document store), Redis (cache), Elasticsearch (search/analytics)
• Docker & Docker Compose (postgres, redis, mongo, elastic, prometheus, grafana)
• Prometheus/Grafana for metrics
• Qodana for static code analysis
Detail & clarity
• Be exhaustive: show every domain module (cart, order, product, inventory, billing, payment, shipment, review, notification, analytics, audit, logging, cache, redis, search, webhook).
• Cross-cutting modules (core, rest, graphql, sandbox) separately.
• High-level flows: user login → token issuance → secured API call → transaction commit → event publication.