# evershopcommerce/evershop architecture

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

- Interactive diagram: https://gitdiagram.com/evershopcommerce/evershop
- Repository: https://github.com/evershopcommerce/evershop

## Overview

##### Main Components
- Frontend Clients: Two distinct frontends exist – one for the customer “frontStore” and one for the administrative backend.
- GraphQL API Gateway: The central API is GraphQL based; it serves as a unified endpoint that aggregates functionality from the various modules.
- Core and Module Services: The monorepo organizes core commerce logic (the “evershop” package) and many discrete modules (catalog, auth, cms, checkout, customer, tax, oms, promotion, etc.). Each module encapsulates its own API endpoints, GraphQL types, resolvers, migration scripts, pages, and services.
- External Services & Integrations: These include payment processors (Stripe, PayPal, COD), file storage (Azure, AWS S3), email providers (SendGrid, Resend), and third-party authentication (Google Login). Also included are the integrations for shipping, notifications, and analytics.
- Database and Persistence: Although not explicitly shown, integration with a relational data store (Postgres is likely given the “postgres-query-builder” package and migration scripts) should be depicted.

##### Relationships & Interactions
- The React-based frontends communicate with the GraphQL API gateway, which in turn calls into the underlying modules.
- Each module has its own set of API endpoints (often using middleware, body parsers, and route files) that are orchestrated to process store operations – for example, product creation, category management, checkout, customer authentication, etc.
- The modules not only communicate with the database for CRUD operations but also emit and respond to events through internal event managers (e.g., for triggering email notifications using SendGrid/Resend or file operations using S3/Azure).
- The system supports extension and customization via a modular architecture, so the core platform loads extensions dynamically from “modules” and “packages” folders.

##### Architectural Patterns and Design Principles
- Modular/Extension-based Architecture: The monorepo is organized by packages, enabling easy plug-and-play of features. Each module is self-contained with its API, GraphQL types, migrations, and pages.
- Layered Separation: There is a clear separation between the presentation layer (React frontends), the business logic layer (GraphQL API resolvers and underlying services), and data persistence (Postgres and possibly external caches).
- Use of Middleware: Many modules leverage middleware functions (as shown by the file naming conventions for route validation, context injection, etc.) for handling API calls and data processing.
- External Integration Abstraction: Distinct packages abstract external integrations (e.g., google_login, s3_file_storage, sendgrid, and azure_file_storage), facilitating easy replacement or extension.

- Rectangles for internal modules and services.
- Notes on how Docker is used to package/deploy the entire application, emphasizing that deployment is containerized.

##### Detailed Steps for the Principal Software Engineer
c. From the API Gateway, branch out into the internal modules. Group these modules by their domain (e.g., Catalog-related modules, Customer/Authentication modules, Checkout, CMS, Payment, Promotion, etc.). Include sample module names if needed (as seen in packages such as “catalog”, “checkout”, “customer”, “cms”, “tax”, “paypal”, “stripe”, “cod”, “oms”, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
  %% Client Layer
  subgraph "Client Layer"
    FS["FrontStore Client (React)"]:::client
    AD["Admin Client (React)"]:::client
  end

  %% API Gateway Layer
  subgraph "API Gateway Layer"
    API["Unified GraphQL API"]:::api
  end

  %% Core & Module Services Layer
  subgraph "Core & Module Services"
    CORE["Core evershop"]:::module
    CAT["Catalog Module"]:::module
    CHK["Checkout Module"]:::module
    CUST["Customer Module"]:::module
    CMS["CMS Module"]:::module
    AUTH["Auth Module"]:::module
    OMS["OMS Module"]:::module
    PROMO["Promotion Module"]:::module
    SET["Setting Module"]:::module
    TAX["Tax Module"]:::module
    PREV["Product Review Module"]:::module
  end

  %% Database Layer
  subgraph "Database Layer"
    DB["PostgreSQL Database"]:::database
  end

  %% External Services & Integrations
  subgraph "External Services"
    %% Payment Processors
    subgraph "Payment Processors"
      PP["PayPal Integration"]:::external
      STR["Stripe Integration"]:::external
      COD["COD Integration"]:::external
    end
    %% File Storage
    subgraph "File Storage"
      AZ["Azure File Storage"]:::external
      S3["AWS S3 File Storage"]:::external
    end
    %% Email Services
    subgraph "Email Services"
      RES["Resend Integration"]:::external
      SG["SendGrid Integration"]:::external
    end
    %% Third-party Authentication
    ATA["Google Login Integration"]:::external
  end

  %% Infrastructure & CI/CD Layer
  subgraph "Infrastructure & CI/CD"
    INFRA["Docker & CI/CD"]:::infra
  end

  %% Connections from Clients to API Gateway
  FS -->|"calls"| API
  AD -->|"calls"| API

  %% Connections from API Gateway to Core & Modules
  API -->|"routes to"| CORE
  API -->|"routes to"| CAT
  API -->|"routes to"| CHK
  API -->|"routes to"| CUST
  API -->|"routes to"| CMS
  API -->|"routes to"| AUTH
  API -->|"routes to"| OMS
  API -->|"routes to"| PROMO
  API -->|"routes to"| SET
  API -->|"routes to"| TAX
  API -->|"routes to"| PREV

  %% Modules to Database
  CORE -->|"CRUD"| DB
  CAT -->|"CRUD"| DB
  CHK -->|"CRUD"| DB
  CUST -->|"CRUD"| DB
  CMS -->|"CRUD"| DB
  AUTH -->|"CRUD"| DB
  OMS -->|"CRUD"| DB
  PROMO -->|"CRUD"| DB
  SET -->|"CRUD"| DB
  TAX -->|"CRUD"| DB
  PREV -->|"CRUD"| DB

  %% Module interactions with External Services
  %% Payment Processors from Checkout Module
  CHK -->|"payment"| PP
  CHK -->|"payment"| STR
  CHK -->|"payment"| COD

  %% File Storage from CMS Module
  CMS -->|"store media"| AZ
  CMS -->|"store media"| S3

  %% Email Services from Promotion Module
  PROMO -->|"notify"| RES
  PROMO -->|"notify"| SG

  %% Third-party Authentication from Auth Module
  AUTH -->|"social login"| ATA

  %% Plugin integration: Product Review linked with Catalog
  CAT -->|"plugin"| PREV

  %% Infrastructure connected to all layers (deploys and monitors)
  INFRA --- API
  INFRA --- CORE

  %% Click Events
  click FS "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/components/frontStore"
  click AD "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/components/admin"
  click API "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/graphql/api"
  click CORE "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop"
  click CAT "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/catalog"
  click CHK "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/checkout"
  click CUST "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/customer"
  click CMS "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/cms"
  click AUTH "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/auth"
  click OMS "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/oms"
  click PROMO "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/promotion"
  click SET "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/setting"
  click TAX "https://github.com/evershopcommerce/evershop/tree/dev/packages/evershop/src/modules/tax"
  click PREV "https://github.com/evershopcommerce/evershop/tree/dev/packages/product_review"
  click PP "https://github.com/evershopcommerce/evershop/tree/dev/packages/paypal"
  click STR "https://github.com/evershopcommerce/evershop/tree/dev/packages/stripe"
  click COD "https://github.com/evershopcommerce/evershop/tree/dev/packages/cod"
  click AZ "https://github.com/evershopcommerce/evershop/tree/dev/packages/azure_file_storage"
  click S3 "https://github.com/evershopcommerce/evershop/tree/dev/packages/s3_file_storage"
  click RES "https://github.com/evershopcommerce/evershop/tree/dev/packages/resend"
  click SG "https://github.com/evershopcommerce/evershop/tree/dev/packages/sendgrid"
  click ATA "https://github.com/evershopcommerce/evershop/tree/dev/packages/google_login"
  click DB "https://github.com/evershopcommerce/evershop/tree/dev/packages/postgres-query-builder"
  click INFRA "https://github.com/evershopcommerce/evershop/tree/dev/Dockerfile"

  %% Styles
  classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
  classDef api fill:#FFB6C1,stroke:#000,stroke-width:2px;
  classDef module fill:#FFE4B5,stroke:#000,stroke-width:2px;
  classDef database fill:#90EE90,stroke:#000,stroke-width:2px;
  classDef external fill:#F08080,stroke:#000,stroke-width:2px;
  classDef infra fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
