# wlayray/order-demo architecture

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

- Interactive diagram: https://gitdiagram.com/wlayray/order-demo
- Repository: https://github.com/wlayray/order-demo

## Overview

##### Main Components of the System
- API Layer: Represented by the “api” directory which includes OpenAPI and protobuf (gRPC) definitions. This layer acts as the external contract for clients and serves as a point of integration.
- Microservices: Each business domain is implemented as its own service:
- Order Service (internal/order): Manages order-related operations, with clear domain, application, adapters, and repository layers. Uses both HTTP and gRPC channels.
- Payment Service (internal/payment): Takes care of payment processing, uses adapters (e.g., ordering via gRPC), application logic, and integrates with external processors like Stripe.
- Stock Service (internal/stock): Manages stock/inventory information. It implements similar architectural patterns (domain, application, adapters) and integrates with external systems (stripe for integrations) and uses PostgreSQL through the ent ORM.
- Goods Service (internal/goods): Likely responsible for handling product catalogs and possibly integrating orders; it includes its own infrastructure and adapters.
- Shared/Common Components: Under internal/common, you have:
- Broker (RabbitMQ): For event-based messaging.
- Client (gRPC and OpenAPI clients): For inter-service communication.
- Database connectivity and discovery (PostgreSQL adapters, etcd integration).
- Logging (using zap), metrics (Prometheus), and tracing (Jaeger).
- External Dependencies and Infrastructure:
- Docker Compose: Presence of docker-compose.yml indicates container orchestration for local development or deployment.
- Prometheus: For monitoring (configuration exists in the “prometheus” directory).
- External payment processors (like Stripe) integrated in both payment and stock modules.

##### Relationships and Interactions
- Microservices communicate with each other via both direct gRPC calls and indirectly through messaging (RabbitMQ, as seen in consumer adapters).
- The API layer exposes endpoints (documented in the OpenAPI spec) which front for one or more microservices.
- Discovery and configuration are central – etcd is used for both storage connectivity and service discovery among the microservices.
- Common cross-cutting concerns (logging, metrics, and tracing) are integrated into all services.

##### Architectural Patterns and Design Principles
- Microservices and Separation of Concerns: Each service (order, payment, stock, goods) is self-contained, featuring domain, application, and infrastructure layers.
- Domain-Driven Design (DDD): Evident from the “domain” directories and the explicit separation into application and adapter layers.
- Adapter/Decorator Patterns: The “adapters” and “decorator” directories show that the project uses patterns to abstract implementation details (e.g., logging, metrics) from business logic.
- Event-Driven Architecture: Use of RabbitMQ for asynchronous communication and handling events between services.

##### Relevant Technologies, Frameworks, and Libraries
- Language: Go
- Communication protocols: gRPC and HTTP
- API Documentation: OpenAPI
- Messaging: RabbitMQ
- Service Discovery: etcd
- ORM: ent (for database interactions, likely with PostgreSQL)
- Monitoring and Tracing: Prometheus (metrics), Jaeger (tracing)
- External APIs: Stripe (payment and stock integrations)

##### Elements
- Clear labels for each major component and sub-module.
- Visual segregation of different types of components (frontend/API vs. backend services vs. shared infrastructure).
- Annotations highlighting the key technologies used (grpc, openAPI, RabbitMQ, PostgreSQL, etcd, Prometheus, Jaeger, Stripe).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client/API Layer
    subgraph "Client/API Layer"
        APILayer["API Layer"]:::api
        OpenAPI["OpenAPI Definitions"]:::api
        OrderPB["Order Protobufs (Order)"]:::api
        StockPB["Stock Protobufs (Stock)"]:::api
    end

    %% Microservices Layer
    subgraph "Microservices"
        subgraph "Order Service"
            OSMain["Order Service Main"]:::order
            OSApp["Order Application Layer"]:::order
            OSAdapters["Order Adapters"]:::order
            OSDomain["Order Domain"]:::order
        end

        subgraph "Payment Service"
            PSMain["Payment Service Main"]:::payment
            PSApp["Payment Application Layer"]:::payment
            PSAdapters["Payment Adapters"]:::payment
            PSStripe["Stripe Processor"]:::payment
        end

        subgraph "Stock Service"
            SSMain["Stock Service Main"]:::stock
            SSApp["Stock Application Layer"]:::stock
            SSAdapters["Stock Adapters"]:::stock
            SSDomain["Stock Domain"]:::stock
            SSStripe["Stripe Integration"]:::stock
        end

        subgraph "Goods Service"
            GSMain["Goods Service Main"]:::goods
            GSAdapters["Goods Adapters"]:::goods
            GSConsumer["Goods Consumer"]:::goods
        end
    end

    %% Shared/Common Components
    subgraph "Shared/Common Services"
        Broker["Broker (RabbitMQ)"]:::common
        Client["Client"]:::common
        Config["Configuration"]:::common
        DB["Database Connectivity"]:::common
        Decorators["Decorators"]:::common
        Discovery["Service Discovery"]:::common
        Logging["Logging"]:::common
        Metrics["Metrics (Prometheus)"]:::common
        Tracing["Tracing (Jaeger)"]:::common
        Server["Server Implementations"]:::common
        Genproto["Genproto (Shared Protobuf)"]:::common
    end

    %% External Infrastructure
    subgraph "External Infrastructure"
        Docker["Docker Compose"]:::external
        Prometheus["Prometheus Monitoring"]:::external
        StripeExt["Stripe External"]:::external
    end

    %% Connections between API Layer and Microservices
    APILayer -->|"HTTP/gRPC"| OSMain
    APILayer -->|"HTTP/gRPC"| PSMain
    APILayer -->|"HTTP/gRPC"| SSMain
    APILayer -->|"HTTP/gRPC"| GSMain

    %% API Layer to Server implementation
    APILayer --> Server

    %% Inter-Service Communication via Common Client
    OSMain -->|"gRPC"| Client
    PSMain -->|"gRPC"| Client
    SSMain -->|"gRPC"| Client
    GSMain -->|"gRPC"| Client

    %% Payment Service adapter calling Order Domain via gRPC
    PSAdapters -->|"gRPC"| OSDomain

    %% Goods Service adapter calling Order Domain via gRPC
    GSAdapters -->|"gRPC"| OSDomain

    %% Asynchronous messaging using Broker (RabbitMQ)
    OSAdapters -->|"async"| Broker
    GSConsumer -->|"async"| Broker

    %% Stock Service using Database connectivity (PostgreSQL via ent ORM)
    SSAdapters -->|"DB"| DB

    %% External Stripe integration for Payment and Stock Services
    PSStripe -->|"Stripe"| StripeExt
    SSStripe -->|"Stripe"| StripeExt

    %% Common cross-cutting concerns: Logging, Metrics, Tracing, Discovery
    OSMain --> Logging
    OSMain --> Metrics
    OSMain --> Tracing
    OSMain --> Discovery

    PSMain --> Logging
    PSMain --> Metrics
    PSMain --> Tracing
    PSMain --> Discovery

    SSMain --> Logging
    SSMain --> Metrics
    SSMain --> Tracing
    SSMain --> Discovery

    GSMain --> Logging
    GSMain --> Metrics
    GSMain --> Tracing
    GSMain --> Discovery

    %% Internal Common: Client uses Genproto definitions
    Client --> Genproto

    %% External Infrastructure connections
    Docker --> APILayer
    Prometheus --> Metrics

    %% Click Events for API Layer
    click APILayer "https://github.com/wlayray/order-demo/tree/main/api"
    click OpenAPI "https://github.com/wlayray/order-demo/tree/main/api/openapi"
    click OrderPB "https://github.com/wlayray/order-demo/tree/main/api/orderpb"
    click StockPB "https://github.com/wlayray/order-demo/tree/main/api/stockpb"

    %% Click Events for Order Service
    click OSMain "https://github.com/wlayray/order-demo/blob/main/internal/order/main.go"
    click OSApp "https://github.com/wlayray/order-demo/tree/main/internal/order/app"
    click OSAdapters "https://github.com/wlayray/order-demo/tree/main/internal/order/adapters"
    click OSDomain "https://github.com/wlayray/order-demo/tree/main/internal/order/domain"

    %% Click Events for Payment Service
    click PSMain "https://github.com/wlayray/order-demo/blob/main/internal/payment/main.go"
    click PSApp "https://github.com/wlayray/order-demo/tree/main/internal/payment/app"
    click PSAdapters "https://github.com/wlayray/order-demo/tree/main/internal/payment/adapters"
    click PSStripe "https://github.com/wlayray/order-demo/blob/main/internal/payment/infrastructure/processor/stripe.go"

    %% Click Events for Stock Service
    click SSMain "https://github.com/wlayray/order-demo/blob/main/internal/stock/main.go"
    click SSApp "https://github.com/wlayray/order-demo/tree/main/internal/stock/app"
    click SSAdapters "https://github.com/wlayray/order-demo/tree/main/internal/stock/adapters"
    click SSDomain "https://github.com/wlayray/order-demo/tree/main/internal/stock/domain"
    click SSStripe "https://github.com/wlayray/order-demo/blob/main/internal/stock/infrastructure/integration/stripe.go"

    %% Click Events for Goods Service
    click GSMain "https://github.com/wlayray/order-demo/blob/main/internal/goods/main.go"
    click GSAdapters "https://github.com/wlayray/order-demo/tree/main/internal/goods/adaptors"
    click GSConsumer "https://github.com/wlayray/order-demo/tree/main/internal/goods/infrastructure/consumer"

    %% Click Events for Shared/Common Components
    click Broker "https://github.com/wlayray/order-demo/tree/main/internal/common/broker"
    click Client "https://github.com/wlayray/order-demo/tree/main/internal/common/client"
    click Config "https://github.com/wlayray/order-demo/tree/main/internal/common/config"
    click DB "https://github.com/wlayray/order-demo/tree/main/internal/common/db"
    click Decorators "https://github.com/wlayray/order-demo/tree/main/internal/common/decorator"
    click Discovery "https://github.com/wlayray/order-demo/tree/main/internal/common/discovery"
    click Logging "https://github.com/wlayray/order-demo/tree/main/internal/common/logging"
    click Metrics "https://github.com/wlayray/order-demo/tree/main/internal/common/metrics"
    click Tracing "https://github.com/wlayray/order-demo/tree/main/internal/common/tracing"
    click Server "https://github.com/wlayray/order-demo/tree/main/internal/common/server"
    click Genproto "https://github.com/wlayray/order-demo/tree/main/internal/common/genproto"

    %% Click Events for External Infrastructure
    click Docker "https://github.com/wlayray/order-demo/blob/main/docker-compose.yml"
    click Prometheus "https://github.com/wlayray/order-demo/blob/main/prometheus/prometheus.yml"

    %% Styles
    classDef api fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef order fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef payment fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef stock fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef goods fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef common fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;
```
