# rigby-sh/solace-medusa-starter architecture

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

- Interactive diagram: https://gitdiagram.com/rigby-sh/solace-medusa-starter
- Repository: https://github.com/rigby-sh/solace-medusa-starter

## Overview

##### Main Components
- Frontend Application (Next.js):
- The project’s source code in the "src" folder indicates that the application’s routing, layout, and UI are split into several modules and pages (for country-specific routes, checkout, account management, blogs, products, etc.).
- The "src/app" directory (with routes like [countryCode]) and "src/modules" directory (organizing features into account, checkout, blog, cart, products, etc.) clearly establish an MVC-like pattern where components, templates, and pages are separated.
- API & Middleware:
- The "src/app/api" layer (e.g., "src/app/api/strapi-revalidate/route.ts") creates endpoints that handle webhook-triggered revalidation from Strapi.
- External Services:
- Medusa 2.0 backend is the eCommerce API powering core operations (cart, products, orders). While this code is not in the repository (but referenced as a prerequisite), the integration happens via environment variables and client-side SDK functions (in "src/lib/data" and hooks).
- Strapi CMS serves as the content management platform (for blog pages, content editing, navigation, etc.) and is integrated via API endpoints and custom revalidation logic.
- Payment Processing (Stripe Integration): Referenced through the checkout modules and payment button wrappers (e.g., "src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx").
- Supporting Layers:
- Preset/Theme files ("preset" folder) for managing UI design tokens and theming.
- Utilities, hooks, and context providers under "src/lib" provide shared functionality for data fetching, state management, and UI utility across modules.
- End-to-End tests in the "e2e" folder using Playwright set up testing infrastructure to simulate user interactions and verify application flows.

##### Relationships & Interactions
- The Next.js frontend communicates with:
- The Medusa backend for commerce-related operations (product information, cart updates, order processing).
- The Strapi CMS through custom API routes (revalidation endpoints) to update and serve dynamic content.
- Payment gateways (e.g., Stripe) via dedicated components and wrappers within the checkout module.
- There is a clear separation between UI modules (organized under "src/modules") and utility/config layers (in "src/lib" and "preset"), while routing and layout composition is managed within "src/app".
- E2E tests simulate user scenarios by interacting with the storefront’s UI; these tests depend on the integrity of the API communication and routes.

##### Architectural Patterns & Design Principles
- Modular Architecture: The application is structured in a modular way. Each feature (account management, checkout, blog, products, etc.) has its own folder with components, templates, and even internal routing.
- Separation of Concerns: Clearly separate the frontend concerns (UI, routing, theming) from the API integration (Medusa, Strapi) and testing.
- Multi-Tenant/Multi-Region Considerations: Use of dynamic [countryCode] folders in the routing suggests support for multiple locales or storefronts.
- Customization & Extensibility: The use of preset plugins and themes allows for easy customization and extensibility of the UI.

##### Relevant Technologies, Frameworks, and Libraries
- Next.js 14 (React-based routing and rendering)
- Medusa 2.0 (eCommerce operations on the backend)
- Strapi CMS (content management and webhook revalidation)
- Playwright (end-to-end testing)
- Stripe (Payment processing integration)
- TypeScript for type safety (via tsconfig.json)
- Tailwind CSS (see tailwind.config.js and CSS files for styling)

##### Elements
- Blocks/Nodes for:
- Frontend Application (Next.js) — including routing layers (src/app) and feature modules (src/modules)
- API endpoints (src/app/api/strapi-revalidate)
- External Services:
- Medusa (eCommerce backend)
- Strapi (CMS)
- Payment Gateway (Stripe)
- From the Frontend Application to Medusa API (for commerce operations)
- From the Frontend Application to Strapi (for content updates and webhook revalidation)
- From the Checkout module to the Stripe Payment Gateway
- Use clear labels for each component.
- Internal Modules/Components (e.g., UI layers, utilities)
- API/Service Integrations (Medusa, Strapi, Payment)
- Testing Framework (E2E tests)
- Optionally, include annotations for middleware, environment configurations (represented by the .env files), and utility layers.

- A comprehensive yet clear separation of the frontend (Next.js), the integration endpoints (API routes for CMS), and the external commerce and content services.
- Modular breakdown of the application’s features and how they interact with external systems (Medusa and Strapi).
- The importance of design principles like separation of concerns, modularity, and extensibility, all of which are evident in the project’s folder structure and engineering choices.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Next.js Application"]:::frontend
        FE2["Routing & Layout"]:::frontend
        FE3["Feature Modules"]:::modules
    end

    %% API & Middleware
    subgraph "API & Middleware"
        API["CMS Revalidation API"]:::api
    end

    %% External Services
    subgraph "External Services"
        MEDUSA["Medusa eCommerce Backend"]:::external
        STRAPI["Strapi CMS"]:::external
        STRIPE["Stripe Payment Gateway"]:::external
    end

    %% Supporting & Configuration
    subgraph "Supporting & Configuration"
        THEME["Theme & Design Tokens"]:::theme
        UTILS["Utilities & Hooks"]:::utils
        MEDUSA_ERR["Medusa Error Handling"]:::utils
        E2E["End-to-End Testing (Playwright)"]:::testing
    end

    %% Relationships
    FE1 --> FE2
    FE1 --> FE3
    FE2 --> UTILS
    FE3 --> UTILS
    FE3 -->|updates| API
    FE3 -->|fetches| MEDUSA
    API -->|triggers| STRAPI
    FE3 -->|initiates| STRIPE
    FE3 --> THEME
    FE1 --> E2E
    MEDUSA -->|handlesErrors| MEDUSA_ERR

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef modules fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef api fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef theme fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef utils fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef testing fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click FE2 "https://github.com/rigby-sh/solace-medusa-starter/tree/main/src/app"
    click FE3 "https://github.com/rigby-sh/solace-medusa-starter/tree/main/src/modules"
    click API "https://github.com/rigby-sh/solace-medusa-starter/blob/main/src/app/api/strapi-revalidate/route.ts"
    click STRIPE "https://github.com/rigby-sh/solace-medusa-starter/blob/main/src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx"
    click THEME "https://github.com/rigby-sh/solace-medusa-starter/tree/main/preset"
    click UTILS "https://github.com/rigby-sh/solace-medusa-starter/tree/main/src/lib"
    click MEDUSA "https://github.com/rigby-sh/solace-medusa-starter/tree/main/src/lib/data"
    click MEDUSA_ERR "https://github.com/rigby-sh/solace-medusa-starter/blob/main/src/lib/util/medusa-error.ts"
    click E2E "https://github.com/rigby-sh/solace-medusa-starter/tree/main/e2e"
```
