# niezgodam/e-commerce architecture

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

- Interactive diagram: https://gitdiagram.com/niezgodam/e-commerce
- Repository: https://github.com/niezgodam/e-commerce

## Overview

##### Project type and purpose
- This is a full-stack, event-driven e-commerce platform.
- Frontend: React + TypeScript SPA.
- Backend: A suite of Spring Boot microservices (auth, cart, catalog, delivery, inventory, order, payment, user) plus an API Gateway.
- Communication: HTTP/REST via API Gateway, asynchronous domain events over Apache Kafka, and reliable delivery via the outbox pattern.

##### High-level architectural components
a. Client / Frontend
- React SPA served on port 80/3000 (calls API Gateway).
b. API Gateway
- Single entry point (JWT filter, routing to downstream services).
c. Microservices
- auth-service, cart-service, catalog-service, delivery-service, inventory-service, order-service, payment-service, user-service.
- Each service owns its own database (Flyway migrations) and uses “shared-outbox” for atomic event publication.
- Each service has synchronous controllers (REST), synchronous clients (in API Gateway / other services), plus asynchronous Kafka listeners & producers.
d. Event Bus
- Apache Kafka cluster (topics defined in shared-kafka).
- Shared-events library defines common event types.
e. Shared Libraries
- shared-events (domain event classes)
- shared-outbox (outbox persistence/poller)
- shared-kafka (topic & group definitions)
- shared-jwt (JWT utility)
f. Databases
- One relational database per microservice (PostgreSQL or MySQL – configured via application.properties).
- Outbox tables per service for reliable event publication.
g. External services
- Stripe for payment processing (configured in payment-service via StripeConfig).

##### Relationships and interactions
- User actions in browser → HTTP(S) → API Gateway → appropriate microservice’s REST controller.
- Inside a service: business logic writes to local database + writes an outbox record in same transaction.
- OutboxPoller (shared-outbox) picks up pending outbox entries and publishes to Kafka.
- Other services subscribe to topics via KafkaListeners and react by updating their own state or producing further events.
- Services may call each other synchronously via Feign/RestTemplate clients (e.g., API Gateway calling CartClient, OrderClient).
- JWT issued by auth-service, validated in API Gateway and downstream filters.
- Payment service interacts with Stripe API synchronously for payment initiation.

##### Architectural patterns and design principles
- Microservices with bounded contexts per business domain (Cart, Catalog, Order, etc.).
- Event-driven architecture using Kafka for decoupling and eventual consistency.
- Outbox pattern to guarantee atomic DB + event write.
- API Gateway pattern for authentication, routing, cross-cutting concerns.
- Shared libraries to avoid duplication (events, JWT, Kafka metadata, outbox mechanics).
- Each service is independently deployable, horizontally scalable, and owned data/store.

- Modular layout:
- Row 1: Client & API Gateway
- Row 2: Microservices (auth, user, catalog, inventory, cart, order, payment, delivery)
- Row 3: Kafka cluster, Databases, External Stripe

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client & API Gateway"
        FE["Frontend SPA"]:::external
        APIGW["API Gateway"]:::sync
    end
    FE -->|"HTTP/REST"| APIGW

    subgraph "Microservices"
        Auth["Auth Service"]:::sync
        User["User Service"]:::sync
        Catalog["Catalog Service"]:::sync
        Inventory["Inventory Service"]:::sync
        Cart["Cart Service"]:::sync
        Order["Order Service"]:::sync
        Payment["Payment Service"]:::sync
        Delivery["Delivery Service"]:::sync
    end

    APIGW -->|"HTTP/REST"| Auth
    APIGW -->|"HTTP/REST"| User
    APIGW -->|"HTTP/REST"| Catalog
    APIGW -->|"HTTP/REST"| Inventory
    APIGW -->|"HTTP/REST"| Cart
    APIGW -->|"HTTP/REST"| Order
    APIGW -->|"HTTP/REST"| Payment
    APIGW -->|"HTTP/REST"| Delivery

    subgraph "Infrastructure"
        Kafka["Apache Kafka"]:::async
        Stripe["Stripe API"]:::external
        subgraph Databases
            AuthDB["Auth DB"]:::persistence
            UserDB["User DB"]:::persistence
            CatalogDB["Catalog DB"]:::persistence
            InventoryDB["Inventory DB"]:::persistence
            CartDB["Cart DB"]:::persistence
            OrderDB["Order DB"]:::persistence
            PaymentDB["Payment DB"]:::persistence
            DeliveryDB["Delivery DB"]:::persistence
        end
        subgraph "Shared Libraries"
            SE["shared-events"]:::persistence
            SO["shared-outbox"]:::persistence
            SK["shared-kafka"]:::persistence
            SJ["shared-jwt"]:::persistence
        end
    end

    Auth -->|"DB + Outbox write"| AuthDB
    User -->|"DB + Outbox write"| UserDB
    Catalog -->|"DB + Outbox write"| CatalogDB
    Inventory -->|"DB + Outbox write"| InventoryDB
    Cart -->|"DB + Outbox write"| CartDB
    Order -->|"DB + Outbox write"| OrderDB
    Payment -->|"DB + Outbox write"| PaymentDB
    Delivery -->|"DB + Outbox write"| DeliveryDB

    SO -->|"Publishes Events"| Kafka
    Kafka -->|"Async Kafka Event"| Auth
    Kafka -->|"Async Kafka Event"| User
    Kafka -->|"Async Kafka Event"| Catalog
    Kafka -->|"Async Kafka Event"| Inventory
    Kafka -->|"Async Kafka Event"| Cart
    Kafka -->|"Async Kafka Event"| Order
    Kafka -->|"Async Kafka Event"| Payment
    Kafka -->|"Async Kafka Event"| Delivery

    Payment -->|"HTTP/REST"| Stripe

    %% Click Events
    click FE "https://github.com/niezgodam/e-commerce/tree/main/frontend/"
    click APIGW "https://github.com/niezgodam/e-commerce/tree/main/services/api-gateway/"
    click Auth "https://github.com/niezgodam/e-commerce/tree/main/services/auth-service/"
    click Cart "https://github.com/niezgodam/e-commerce/tree/main/services/cart-service/"
    click Catalog "https://github.com/niezgodam/e-commerce/tree/main/services/catalog-service/"
    click Delivery "https://github.com/niezgodam/e-commerce/tree/main/services/delivery-service/"
    click Inventory "https://github.com/niezgodam/e-commerce/tree/main/services/inventory-service/"
    click Order "https://github.com/niezgodam/e-commerce/tree/main/services/order-service/"
    click Payment "https://github.com/niezgodam/e-commerce/tree/main/services/payment-service/"
    click User "https://github.com/niezgodam/e-commerce/tree/main/services/user-service/"
    click SE "https://github.com/niezgodam/e-commerce/tree/main/libs/shared-events/"
    click SO "https://github.com/niezgodam/e-commerce/tree/main/libs/shared-outbox/"
    click SK "https://github.com/niezgodam/e-commerce/tree/main/libs/shared-kafka/"
    click SJ "https://github.com/niezgodam/e-commerce/tree/main/libs/shared-jwt/"

    %% Styles
    classDef sync fill:#ccf,stroke:#333,stroke-width:1px
    classDef async fill:#fca,stroke:#333,stroke-width:1px
    classDef persistence fill:#eee,stroke:#333,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px
```
