# andrewyapkj/stripe-subscriptions-demo architecture

> Architecture diagram of the GitHub repository andrewyapkj/stripe-subscriptions-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrewyapkj/stripe-subscriptions-demo
- Repository: https://github.com/andrewyapkj/stripe-subscriptions-demo

## Overview

##### Project type and purpose
- This is a full-stack, subscription-based web application built with Next.js (React + Server-Side Rendering / Serverless API Routes) that integrates deeply with Stripe for checkout sessions, subscription management, and customer portal access.

##### File structure
- Top-level:
- package.json / lockfile: npm dependencies
- next.config.ts, tsconfig.json: Next.js and TypeScript configuration
- public/: static assets (images, favicon)
- src/app/: the “App Router” directory containing both UI pages and API route folders
- src/app/api/: each folder under here is a Next.js Serverless Function handling a Stripe API integration endpoint
- subscription-plans: GET plans
- create-checkout-session: POST to create Stripe Checkout Session
- create-portal-session: POST to create a customer portal session
- check-session: POST to verify session status
- webhooks/stripe: POST to receive and process Stripe webhook events
- src/app/: UI pages and layouts
- page.tsx: landing page & categories
- subscriptions/page.js: pricing page that calls subscription-plans API
- account/page.js: user dashboard; may call check-session or portal APIs
- success/page.js: order confirmation
- layout.tsx, globals.css: root layout and global styling

##### README for additional insights
- Tech stack: Next.js 15, React 19, TypeScript, Tailwind CSS
- Stripe elements used: Checkout, Subscriptions, Customer Portal, Webhooks
- No external database—Stripe is the system of record for payments/subscriptions
- Dev flow: environment variables, local Stripe CLI for testing webhooks

a. Main components (group them into layers):
- Client Layer (Browser / Mobile)
– React pages (landing, pricing, account, success) served by Next.js
– Static assets (CSS, images, fonts) served from CDN or /public
- Server Layer (Next.js App + API Routes)
– UI Server (SSR/SSG rendering)
– API Functions: subscription-plans, create-checkout-session, create-portal-session, check-session, webhooks/stripe
- External Services
– Stripe API (Checkout Sessions, Subscriptions, Customer Portal endpoints)
– Stripe Webhooks delivering events to /api/webhooks/stripe
- Development Tools (optional layer)
– Stripe CLI for local webhook forwarding
1. Client → Next.js UI Server: request page or static asset
2. UI → Client: HTML/CSS/JS
3. Client (browser JS) → Next.js API Route (e.g., subscription-plans): fetch available plans
4. Client → API: create-checkout-session → Next.js Function calls Stripe API → returns session ID → Browser redirects to Stripe Checkout
5. Stripe → Browser: hosted checkout experience
6. Stripe → Next.js webhook endpoint: asynchronous event (checkout.session.completed, subscription.created, etc.)
7. Next.js webhook handler processes event (e.g., update UI state; no DB here)
8. Client → API: create-portal-session → Next.js calls Stripe Customer Portal endpoint → returns portal URL → Browser redirect
9. Client → API: check-session to poll payment status
c. Architectural patterns and design principles:
- Serverless Functions / API Routes for micro-endpoints
- SSR/SSG hybrid via Next.js App Router
- Stripe as external system of record (eliminates internal database for billing)
- Separation of Concerns: UI components vs. API logic vs. external integration
d. Key technologies to annotate:
- Next.js 15 (App Router, server components, edge/serverless functions)
- React 19 (client components)
- Tailwind CSS for styling
- Stripe SDK / stripe-node for API calls
- Environment variables (.env.local) for Stripe keys

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["Browser / UI"]:::frontend
        Static["Static Assets (CDN)"]:::static
        Landing["Landing Page"]:::frontend
        Pricing["Subscriptions Page"]:::frontend
        Account["Account Dashboard Page"]:::frontend
        Success["Order Confirmation Page"]:::frontend
        NotFound["404 / Not Found Handler"]:::frontend
        Layout["Root Layout"]:::frontend
        Globals["Global Stylesheet"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        UI_Server["Next.js UI Server (SSR/SSG)"]:::api
        PlanAPI["GET /api/subscription-plans"]:::api
        CheckoutAPI["POST /api/create-checkout-session"]:::api
        PortalAPI["POST /api/create-portal-session"]:::api
        CheckAPI["POST /api/check-session"]:::api
        WebhookAPI["POST /api/webhooks/stripe"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Stripe["Stripe Service"]:::external
    end

    %% Config & Docs
    subgraph "Project Configurations"
        direction TB
        NextConfig["next.config.ts"]:::static
        TSConfig["tsconfig.json"]:::static
        PackageJSON["package.json"]:::static
        PackageLock["package-lock.json"]:::static
        ESLint["eslint.config.mjs"]:::static
        PostCSS["postcss.config.mjs"]:::static
        README["README.md"]:::static
    end

    %% Connections
    Client --> UI_Server
    UI_Server --> Client
    UI_Server --> Landing
    UI_Server --> Pricing
    UI_Server --> Account
    UI_Server --> Success
    UI_Server --> NotFound

    Client --> Static
    Client --> PlanAPI
    PlanAPI -->|"fetch plans"|Stripe
    Stripe -->|"plans data"|PlanAPI
    PlanAPI --> Client

    Client --> CheckoutAPI
    CheckoutAPI -->|"create checkout session"|Stripe
    Stripe --> CheckoutAPI
    CheckoutAPI --> Client

    Client --> PortalAPI
    PortalAPI -->|"create portal session"|Stripe
    Stripe --> PortalAPI
    PortalAPI --> Client

    Client --> CheckAPI
    CheckAPI --> Stripe
    CheckAPI --> Client

    Stripe --.-> WebhookAPI
    WebhookAPI --> Client

    %% Click Events
    click NextConfig "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/next.config.ts"
    click TSConfig "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/package.json"
    click PackageLock "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/package-lock.json"
    click Static "https://github.com/andrewyapkj/stripe-subscriptions-demo/tree/main/public/"
    click Globals "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/globals.css"
    click Layout "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/layout.tsx"
    click Landing "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/page.tsx"
    click Pricing "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/subscriptions/page.js"
    click Account "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/app/account/page.js"
    click Success "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/success/page.js"
    click NotFound "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/not-found.tsx"
    click PlanAPI "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/api/subscription-plans/route.js"
    click CheckoutAPI "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/api/create-checkout-session/route.js"
    click PortalAPI "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/api/create-portal-session/route.js"
    click CheckAPI "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/api/check-session/route.js"
    click WebhookAPI "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/src/app/api/webhooks/stripe/route.js"
    click ESLint "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/eslint.config.mjs"
    click PostCSS "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/postcss.config.mjs"
    click README "https://github.com/andrewyapkj/stripe-subscriptions-demo/blob/main/README.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef external fill:#ffe5b4,stroke:#ab6500,stroke-width:2px
    classDef static fill:#e2e3e5,stroke:#6c757d,stroke-dasharray: 5 5
```
