How openshiporg/openfront works
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).