# openshiporg/openfront architecture

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

- Interactive diagram: https://gitdiagram.com/openshiporg/openfront
- Repository: https://github.com/openshiporg/openfront

## Overview

##### Core Components
- Frontend (Storefront) – The project uses Next.js. Notice the “app”, “storefront”, and “pages” folders, with dynamic routes for accounts, products, checkout, search, etc. These represent the client‑facing views and components.
- Admin/CMS Dashboard – The “keystone” folder (with models, queries, mutations, themes, screens, and utilities) and the “dashboard” routes lost within “app/dashboard” indicate a fully featured Keystone Admin UI for managing the database.
- API Layer – The GraphQL API is exposed under “pages/api/graphql.js” and related endpoints (e.g. API webhooks for payment providers). This layer ties together data exchange between the frontend, Keystone, and external services.
- Database – With a “schema.prisma” file and DATABASE_URL variables in the .env setup, a PostgreSQL database is used to persist all data.
- External Integration Adapters – Directories like “paymentProviderAdapters” and “shippingProviderAdapters” show that the application integrates with third‑party payment and shipping providers.
- Utility and Shared Libraries – Common modules such as “storefront/lib” and various “keystone/utils” encapsulate business logic, seeding processes, and helper functions.

##### Relationships and Data Flow
- The Next.js storefront communicates with the GraphQL API endpoints to fetch product data, manage carts, and handle orders.
- The GraphQL API (hosted in “pages/api”) acts as a gateway—using Keystone logic—to query or mutate data stored in Postgres.
- Keystone models and mutations reflect the domain entities (orders, products, customers, etc.) and enable CRUD operations via the Admin UI, which is accessible at “/dashboard”.
- The system integrates with external services through dedicated adapters (for Stripe, PayPal, Shippo, etc.) that transform requests/responses between the internal API and payment/shipping endpoints.

##### Architectural Patterns
- Separation of Concerns: Notice the clear demarcation between the user‐facing storefront (Next.js pages/components) and the administrative backend (Keystone). The GraphQL API serves as the integration layer between them.
- Modular design: The project is divided into discrete modules (e.g., account, checkout, cart, etc. in the “storefront/modules” folder and similar segmentation under “keystone/models”, “keystone/mutations”, etc.) which suggests component reusability and clear responsibilities.
- MVC-like structure in portions: Keystone’s models (data), queries/mutations (controllers), and Admin UI screens/views (views) demonstrate an MVC or similar layered architecture.
- Adapter Pattern: The separate directories for payment and shipping adapters encapsulate external integrations.

##### Technological Stack
- Next.js – for server‑side rendering, dynamic routing, and UI components in the storefront.
- Keystone.js – for CMS/administrative backend, built on Prisma with Postgres as the database.
- GraphQL – the API layer that defines queries and mutations.
- External libraries: Payment adapters (Stripe, PayPal, etc.), Shipping adapters (Shippo, Shipengine, etc.), and utility libraries (such as context providers, hooks, and theming for Keystone and storefront).

## Diagram (Mermaid)

```mermaid
flowchart TD
  
  %% Frontend Layer
  subgraph "Frontend (Next.js Storefront)"
    FS1["Storefront Routes"]
    FS2["Storefront Interface"]
    FS3["Storefront Modules"]
    FS4["Storefront Shared Lib"]
  end
  
  %% API Layer
  subgraph "API Layer"
    API1["GraphQL Endpoint"]
    API2["Webhook Endpoints"]
  end
  
  %% Admin/CMS Dashboard
  subgraph "Admin/CMS Dashboard (Keystone)"
    KS1["Keystone Admin"]
    KS2["Dashboard Routes"]
    KS3["Keystone Utilities"]
  end
  
  %% Database Layer
  subgraph "Database"
    DB1["PostgreSQL Database (Prisma Schema)"]
  end
  
  %% External Integrations
  subgraph "External Integrations"
    EX1["Payment Provider Adapters"]
    EX2["Shipping Provider Adapters"]
  end

  %% Data Flow Connections
  %% Frontend -> API Layer
  FS1 -->|"fetches data"| API1
  FS2 -->|"fetches data"| API1
  FS3 -->|"fetches data"| API1
  FS4 -->|"provides helpers"| API1
  
  %% API Layer -> Admin Layer
  API1 -->|"queries/mutates"| KS1
  
  %% Admin internal connections
  KS2 -->|"renders UI"| KS1
  KS3 ---|"assists with"| KS1
  
  %% Admin -> Database
  KS1 -->|"CRUD operations"| DB1
  
  %% API Layer -> External Integrations
  API1 -->|"external call"| EX1
  API1 -->|"external call"| EX2
  
  %% Admin -> External Integrations
  KS1 -->|"external call"| EX1
  KS1 -->|"external call"| EX2

  %% Click Events for Frontend
  click FS1 "https://github.com/openshiporg/openfront/tree/master/app/(storefront)"
  click FS2 "https://github.com/openshiporg/openfront/tree/master/storefront"
  click FS3 "https://github.com/openshiporg/openfront/tree/master/storefront/modules"
  click FS4 "https://github.com/openshiporg/openfront/tree/master/storefront/lib"
  
  %% Click Events for Admin/CMS Dashboard
  click KS1 "https://github.com/openshiporg/openfront/tree/master/keystone"
  click KS2 "https://github.com/openshiporg/openfront/tree/master/app/dashboard"
  click KS3 "https://github.com/openshiporg/openfront/tree/master/keystone/utils"
  
  %% Click Events for API Layer
  click API1 "https://github.com/openshiporg/openfront/blob/master/pages/api/graphql.js"
  click API2 "https://github.com/openshiporg/openfront/tree/master/pages/api/webhooks"
  
  %% Click Event for Database
  click DB1 "https://github.com/openshiporg/openfront/blob/master/schema.prisma"
  
  %% Click Events for External Integrations
  click EX1 "https://github.com/openshiporg/openfront/tree/master/paymentProviderAdapters"
  click EX2 "https://github.com/openshiporg/openfront/tree/master/shippingProviderAdapters"

  %% Styles
  class FS1,FS2,FS3,FS4 frontend
  class API1,API2 api
  class KS1,KS2,KS3 admin
  class DB1 database
  class EX1,EX2 external
  
  %% Class Definitions
  classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:2px;
  classDef api fill:#F1F8E9,stroke:#558B2F,stroke-width:2px;
  classDef admin fill:#FFECB3,stroke:#FFA000,stroke-width:2px;
  classDef database fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
  classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
```
