# mathew-gao/subscription-starter architecture

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

- Interactive diagram: https://gitdiagram.com/mathew-gao/subscription-starter
- Repository: https://github.com/mathew-gao/subscription-starter

## Overview

##### Main System Components

a) Frontend Layer (Next.js Application):
- Client-side components (under /components/ui)
- Authentication forms
- Account management
- Pricing interface
- Payment flows

b) Backend Layer:
- Next.js API routes (under /app/api)
- Webhook handlers
- Authentication endpoints
- Middleware

c) External Services:
- Supabase (Authentication & Database)
- Stripe (Payment Processing)

##### Component Relationships

a) Client-Server Flow:
- User interactions with the frontend
- API calls to backend endpoints
- Authentication flows
- Payment processing routes

b) External Service Integration:
- Supabase authentication flows
- Stripe payment processing
- Webhook communication paths

##### Related components
**Frontend Layer:**
- Public Pages (/, /signin, /account)
- Protected Routes
- UI Components
- Auth Forms

**Backend Layer:**
- API Routes
- Webhook Handlers
- Middleware

**External Services:**
- Supabase
- Auth
- Database
- Stripe
- Checkout
- Customer Portal
- Webhooks

##### Critical paths
- User authentication flow
- Subscription purchase flow
- Webhook processing flow
- Database synchronization

**[User Browser] → [Next.js Frontend] → [Next.js API Routes]**
- ↕               ↕                      ↕
**[Supabase Auth] ← → [Middleware] ← → [Stripe Payments]**
- ↕                                     ↕
**[Supabase DB] ← ─ ─ ─ ─ ─ ─ ─ ─ ─ [Stripe Webhooks]**

##### Document all external service connections

This architecture should emphasize the project's subscription-based SaaS nature while showing the integration between Next.js, Supabase, and Stripe.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        Browser["Web Browser"]
        Pages["Application Pages"]
        UIComp["UI Components"]:::ui
        AuthForms["Authentication Forms"]:::ui
        AcctForms["Account Forms"]:::ui
        PricingUI["Pricing Interface"]:::ui
    end

    subgraph APILayer["Backend API Layer"]
        APIRoutes["API Routes"]
        WebhookHandler["Webhook Handler"]:::api
        AuthEndpoints["Auth Endpoints"]:::auth
        MW["Middleware"]:::middleware
    end

    subgraph ExternalServices["External Services"]
        direction TB
        subgraph SupabaseService["Supabase"]
            SupaAuth["Authentication"]
            SupaDB[(Database)]
        end
        
        subgraph StripeService["Stripe"]
            StripePayments["Payment Processing"]
            StripeWebhooks["Webhooks"]
            StripePortal["Customer Portal"]
        end
    end

    subgraph Integration["Integration Layer"]
        StripeUtils["Stripe Utils"]:::utils
        SupabaseUtils["Supabase Utils"]:::utils
        AuthHelpers["Auth Helpers"]:::utils
    end

    %% Relationships
    Browser --> Pages
    Pages --> UIComp
    Pages --> AuthForms
    Pages --> AcctForms
    Pages --> PricingUI
    
    UIComp --> APIRoutes
    AuthForms --> AuthEndpoints
    AcctForms --> APIRoutes
    PricingUI --> APIRoutes
    
    APIRoutes --> MW
    MW --> StripeUtils
    MW --> SupabaseUtils
    MW --> AuthHelpers
    
    StripeUtils --> StripePayments
    StripeWebhooks --> WebhookHandler
    WebhookHandler --> SupaDB
    
    SupabaseUtils --> SupaAuth
    SupabaseUtils --> SupaDB
    AuthHelpers --> SupaAuth

    %% Styling
    classDef ui fill:#e1f5fe,stroke:#01579b
    classDef api fill:#fff3e0,stroke:#e65100
    classDef auth fill:#e8f5e9,stroke:#1b5e20
    classDef middleware fill:#f3e5f5,stroke:#4a148c
    classDef utils fill:#fff8e1,stroke:#ff6f00

    %% Click Events
    click AuthForms "https://github.com/Mathew-Gao/subscription-starter/tree/main/components/ui/AuthForms/"
    click AcctForms "https://github.com/Mathew-Gao/subscription-starter/tree/main/components/ui/AccountForms/"
    click PricingUI "https://github.com/Mathew-Gao/subscription-starter/blob/main/components/ui/Pricing/Pricing.tsx"
    click WebhookHandler "https://github.com/Mathew-Gao/subscription-starter/blob/main/app/api/webhooks/route.ts"
    click AuthEndpoints "https://github.com/Mathew-Gao/subscription-starter/tree/main/app/auth/"
    click MW "https://github.com/Mathew-Gao/subscription-starter/blob/main/middleware.ts"
    click StripeUtils "https://github.com/Mathew-Gao/subscription-starter/tree/main/utils/stripe/"
    click SupabaseUtils "https://github.com/Mathew-Gao/subscription-starter/tree/main/utils/supabase/"
    click AuthHelpers "https://github.com/Mathew-Gao/subscription-starter/tree/main/utils/auth-helpers/"
    click UIComp "https://github.com/Mathew-Gao/subscription-starter/tree/main/components/ui/"
    click Pages "https://github.com/Mathew-Gao/subscription-starter/tree/main/app/"
```
