# medusajs/nextjs-starter-medusa architecture

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

- Interactive diagram: https://gitdiagram.com/medusajs/nextjs-starter-medusa
- Repository: https://github.com/medusajs/nextjs-starter-medusa

## Overview

##### Main System Components

a) Frontend Layer (Next.js Application)
- Client-side Components
- Server Components
- App Router Structure
- Static/Dynamic Routes

b) Backend Layer (Medusa Server)
- API Endpoints
- Commerce Modules
- Payment Integration (Stripe)

c) External Services
- Stripe Payment Processing
- Content Delivery Network (for static assets)

##### Architectural Patterns to Highlight

a) Next.js App Router Architecture
- Route Groups: (checkout), (main)
- Dynamic Routes: [countryCode], [handle], etc.
- Parallel Routes: @dashboard, @login
- Loading and Error States

b) Module-based Structure
- Account Management
- Cart Management
- Checkout Flow
- Product Management
- Layout Components

##### Specific Implementation Details

a) Core Modules (src/modules/):
- Account
- Cart
- Checkout
- Products
- Layout
- Common Components

b) Data Flow Layer (src/lib/):
- Context Providers
- Data Fetching
- Hooks
- Utilities

**┌─ Client Browser ─────────────────────────────────────┐**

- ┌─ Next.js Frontend ──────────────────────────┐    │
- ┌─ App Router ─────┐ ┌─ Modules ─────────┐  │    │
- Dynamic Routes │ │ - Account         │  │    │
- Loading States│ │ - Cart            │  │    │
- Error Handling│ │ - Checkout        │  │    │
- ┘ │ - Products        │  │    │
- Layout          │  │    │
- ┌─ Library ──────┐ └─────────────────┘  │    │
- Context      │                      │    │
- Data Fetch   │ ┌─ Components ────┐  │    │
- Hooks        │ │ - UI Elements   │  │    │
- Utils        │ │ - Forms        │  │    │
- ┘ └────────────────┘  │    │
- ┘    │
- ↕                       │
- ↕───────────────────────┘
- ↕
**┌─────────────────────────↕───────────────────────┐**
- Medusa Backend Server (API)             │
- ┬─────────────────────────────┘
- ↕
**┌───────────────────↕─────────────────────────────┐**
- External Services (Stripe)               │
- ┘

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Browser"]
        subgraph Frontend["Next.js Frontend"]
            subgraph AppRouter["App Router"]
                MainRoutes["(main) Routes"]:::router
                CheckoutRoutes["(checkout) Routes"]:::router
                AccountRoutes["Account Routes"]:::router
                DynamicRoutes["Dynamic Routes"]:::router
            end

            subgraph Modules["Core Modules"]
                Account["Account Management"]:::module
                Cart["Cart Management"]:::module
                Checkout["Checkout Flow"]:::module
                Products["Product Management"]:::module
                Layout["Layout Components"]:::module
                Store["Store Management"]:::module
                Collections["Collections"]:::module
                Categories["Categories"]:::module
                Order["Order Management"]:::module
                Shipping["Shipping"]:::module
                Home["Home"]:::module
            end

            subgraph Library["Library Layer"]
                Context["Context Providers"]:::lib
                DataFetch["Data Fetching"]:::lib
                Hooks["Hooks"]:::lib
                Utils["Utilities"]:::lib
            end

            subgraph Components["Common Components"]
                UI["UI Elements"]:::component
                Icons["Icons"]:::component
                Skeletons["Loading States"]:::component
            end

            subgraph Payment["Payment Integration"]
                StripeWrapper["Stripe Wrapper"]:::payment
                PaymentComponents["Payment Components"]:::payment
            end
        end
    end

    subgraph Backend["Medusa Backend Server"]
        API["API Endpoints"]:::backend
        CommerceModules["Commerce Modules"]:::backend
    end

    subgraph External["External Services"]
        Stripe["Stripe Payment Processing"]:::external
        CDN["Content Delivery Network"]:::external
    end

    %% Connections
    Frontend <--> Backend
    Backend <--> External
    Payment --> Stripe

    %% Click Events
    click MainRoutes "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/app/[countryCode]/(main)"
    click CheckoutRoutes "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/app/[countryCode]/(checkout)"
    click AccountRoutes "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/app/[countryCode]/(main)/account"
    click Account "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/account"
    click Cart "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/cart"
    click Checkout "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/checkout"
    click Products "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/products"
    click Layout "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/layout"
    click Context "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/lib/context"
    click DataFetch "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/lib/data"
    click Hooks "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/lib/hooks"
    click Utils "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/lib/util"
    click StripeWrapper "https://github.com/medusajs/nextjs-starter-medusa/blob/main/src/modules/checkout/components/payment-wrapper/stripe-wrapper.tsx"
    click PaymentComponents "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/checkout/components/payment"
    click UI "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/common/components"
    click Icons "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/common/icons"
    click Store "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/store"
    click Collections "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/collections"
    click Categories "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/categories"
    click Skeletons "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/skeletons"
    click Order "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/order"
    click Home "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/home"
    click Shipping "https://github.com/medusajs/nextjs-starter-medusa/tree/main/src/modules/shipping"

    %% Styles
    classDef router fill:#e1f5fe,stroke:#01579b
    classDef module fill:#e8f5e9,stroke:#2e7d32
    classDef lib fill:#fff3e0,stroke:#ff6f00
    classDef component fill:#f3e5f5,stroke:#7b1fa2
    classDef payment fill:#fce4ec,stroke:#c2185b
    classDef backend fill:#efebe9,stroke:#3e2723
    classDef external fill:#f1f8e9,stroke:#33691e

    %% Legend
    subgraph Legend
        Router["Router Component"]:::router
        ModuleComponent["Module Component"]:::module
        LibComponent["Library Component"]:::lib
        UIComponent["UI Component"]:::component
        PaymentComponent["Payment Component"]:::payment
        BackendComponent["Backend Component"]:::backend
        ExternalComponent["External Service"]:::external
    end
```
