How andrewyapkj/stripe-subscriptions-demo works
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