# stpfeffer/merkana architecture

> Architecture diagram of the GitHub repository stpfeffer/merkana, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stpfeffer/merkana
- Repository: https://github.com/stpfeffer/merkana

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client UIs / Integrators"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        Gateway["API Gateway<br/>(merkana-web)"]:::api
        GraphQL["GraphQL API Layer"]:::api
        REST["REST API Layer"]:::api
        Auth["Authentication Module<br/>(JWT)"]:::api
    end

    %% Application & Domain
    subgraph "Domain Modules" 
        direction TB
        Catalog["Catalog Module"]:::domain
        Cart["Cart Module"]:::domain
        Order["Order Module"]:::domain
        Product["Product Module"]:::domain
        Promotion["Promotion Module"]:::domain
        Inventory["Inventory Module"]:::domain
        Billing["Billing Module"]:::domain
        Payment["Payment Module"]:::domain
        User["User Module"]:::domain
        Review["Review Module"]:::domain
        Shipment["Shipment Module"]:::domain
        CMS["CMS Module"]:::domain
        Media["Media Module"]:::domain
        Geo["Geo Location Module"]:::domain
        Webhook["Webhook Module"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Modules"
        direction TB
        Cache["Cache Infrastructure"]:::infra
        RedisInfra["Redis Infrastructure"]:::infra
        Logging["Logging Infrastructure"]:::infra
        Analytics["Analytics Infrastructure"]:::infra
        Audit["Audit Infrastructure"]:::infra
        Mail["Mail Infrastructure"]:::infra
        Notification["Notification Infrastructure"]:::infra
        Search["Search/Elasticsearch"]:::infra
        Sandbox["Sandbox Testing Support"]:::infra
    end

    %% Shared Core
    Core["Shared Core<br/>(context, DTOs, utils)"]:::core

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres[(PostgreSQL)]:::datastore
        Mongo[(MongoDB)]:::datastore
        RedisDB[(Redis DB)]:::datastore
        Elastic[(Elasticsearch)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PayGateway["Payment Gateway"]:::external
        SMTP["Email SMTP"]:::external
        ShipProvider["Shipping Provider"]:::external
        WebhookTarget["Webhook Targets"]:::external
    end

    %% Observability
    subgraph "Observability Stack"
        direction TB
        Prometheus["Prometheus"]:::obs
        Grafana["Grafana"]:::obs
    end

    %% Config & Deployment
    Config["Docker & Compose Configurations"]:::core

    %% Relationships
    Client -->|REST/GraphQL| Gateway
    Gateway -->|GraphQL Query| GraphQL
    Gateway -->|REST Call| REST
    Gateway -->|Auth Filter| Auth
    Auth -->|validates JWT| Gateway

    Gateway -->|calls| Catalog
    Gateway -->|calls| Cart
    Gateway -->|calls| Order
    Gateway -->|calls| Product
    Gateway -->|calls| Promotion
    Gateway -->|calls| Inventory
    Gateway -->|calls| Billing
    Gateway -->|calls| Payment
    Gateway -->|calls| User
    Gateway -->|calls| Review
    Gateway -->|calls| Shipment
    Gateway -->|calls| CMS
    Gateway -->|calls| Media
    Gateway -->|calls| Geo
    Gateway -->|calls| Webhook

    %% Domain to Core
    Catalog --> Core
    Cart --> Core
    Order --> Core
    Product --> Core
    Promotion --> Core
    Inventory --> Core
    Billing --> Core
    Payment --> Core
    User --> Core
    Review --> Core
    Shipment --> Core
    CMS --> Core
    Media --> Core
    Geo --> Core
    Webhook --> Core

    %% Domain to Data Stores/Infra
    Cart -->|JPA Repo| Postgres
    Order -->|JPA Repo| Postgres
    Product -->|JPA Repo| Postgres
    Catalog -->|JPA Repo| Postgres
    Promotion -->|JPA Repo| Postgres
    Inventory -->|JPA Repo| Postgres
    Billing -->|JPA Repo| Postgres
    User -->|JPA Repo| Postgres
    Shipment -->|JPA Repo| Postgres
    Review -->|Mongo Repo| Mongo
    Analytics -->|indexes| Elastic
    Search -->|interacts| Elastic
    Cache -->|caches| Postgres
    RedisInfra -->|caches| RedisDB

    %% Infra integration
    Mail --> SMTP
    Notification --> ShipProvider
    Webhook --> WebhookTarget
    Audit -->|writes events| Mongo
    Logging -->|collects logs| Elastic
    Analytics -->|reads events| Mongo
    Sandbox -->|test support| Core

    %% Observability flow
    Core -->|export metrics| Prometheus
    Prometheus -->|visualizes| Grafana

    %% Config
    Config -->|deploys containers| Postgres
    Config -->|deploys containers| RedisDB
    Config -->|deploys containers| Mongo
    Config -->|deploys containers| Elastic
    Config -->|deploys containers| Prometheus
    Config -->|deploys containers| Grafana
    Config -->|configures| Gateway

    %% Click Events
    click Gateway "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-web/src/main/java/com/merkana/web"
    click GraphQL "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-graphql/pom.xml"
    click REST "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-rest/pom.xml"
    click Core "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-core/src/main/java/com/merkana/core"
    click Cache "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-cache/src/main/java/com/merkana/cache"
    click RedisInfra "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-redis/src/main/java/com/merkana/redis"
    click Logging "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-logging/pom.xml"
    click Analytics "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-analytics/pom.xml"
    click Audit "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-audit/pom.xml"
    click Mail "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-mail/pom.xml"
    click Notification "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-notification/pom.xml"
    click Search "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-search/pom.xml"
    click Sandbox "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-sandbox/pom.xml"
    click Auth "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-auth/pom.xml"
    click Catalog "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-catalog/pom.xml"
    click Cart "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-cart/src/main/java/com/merkana/cart"
    click Order "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-order/src/main/java/com/merkana/order"
    click Product "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-product/src/main/java/com/merkana/product"
    click Promotion "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-promotion/src/main/java/com/merkana/promotion"
    click Inventory "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-inventory/pom.xml"
    click Billing "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-billing/pom.xml"
    click Payment "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-payment/pom.xml"
    click User "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-user/pom.xml"
    click Review "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-review/src/main/java/com/merkana/review"
    click Shipment "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-shipment/pom.xml"
    click CMS "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-cms/pom.xml"
    click Media "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-media/pom.xml"
    click Geo "https://github.com/stpfeffer/merkana/tree/dev/modules/merkana-geo/src/main/java/com/merkana/geo"
    click Webhook "https://github.com/stpfeffer/merkana/blob/dev/modules/merkana-webhook/pom.xml"
    click Config "https://github.com/stpfeffer/merkana/blob/dev/docker-compose.yml"

    %% Styles
    classDef api fill:#1f77b4,stroke:#333,stroke-width:1px
    classDef domain fill:#2ca02c,stroke:#333,stroke-width:1px
    classDef infra fill:#ff7f0e,stroke:#333,stroke-width:1px
    classDef core fill:#7f7f7f,stroke:#333,stroke-width:1px
    classDef datastore fill:#8c564b,stroke:#333,stroke-width:1px
    classDef external fill:#9467bd,stroke:#333,stroke-width:1px
    classDef obs fill:#bcbd22,stroke:#333,stroke-width:1px
```
