Ghoststack Architecture

How the pieces fit together.

Stack Overview

┌─────────────────────────────────────────────────────┐
│                    Frontend                          │
│  Next.js App Router + DaisyUI                       │
│  app/page.tsx, app/dashboard/, app/pricing/         │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│                   API Routes                         │
│  app/api/stripe/, app/api/auth/, app/api/webhooks/     │
└─────────────────────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ Supabase │  │  Stripe  │  │  Resend  │
    │ Auth +DB │  │ Payments │  │  Email   │
    └──────────┘  └──────────┘  └──────────┘

Request Flows

Page Load (Server Component)

User visits /dashboard
  → proxy.ts checks auth
  → app/dashboard/page.tsx loads
  → Page verifies user and lib/supabase/db.ts queries DB
  → Page renders with data

Auth (Magic Link)

User enters email on /login
  → Supabase sends magic link
  → User clicks link
  → /callback exchanges code for session
  → Redirect to /dashboard

Payment

User clicks "Subscribe"
  → /api/stripe/checkout creates session
  → Stripe hosts checkout
  → Webhook hits /api/webhooks/stripe
  → lib/supabase/db.ts updates subscription

Key Files

Layer	Files	Purpose
Pages	`app/page.tsx`, `app/dashboard/`	UI and routing
API	`app/api/stripe/`, `app/api/webhooks/`	Backend logic
Auth	`proxy.ts`, `lib/supabase/server.ts`	Session + protection
Database	`lib/supabase/db.ts`, `supabase/setup.sql`	Queries + schema
Payments	`lib/stripe.ts`, `lib/plans.ts`	Stripe + pricing
Email	`lib/resend.tsx`	Templates + sending
App settings	`.env.local`	Local service configuration; may contain secrets
Agent instructions	`AGENTS.md`	Shared project guidance; never secrets

Supabase Clients

Three clients for different contexts:

Client	File	When to Use
Browser	`lib/supabase/client.ts`	Client components (`"use client"`)
Server	`lib/supabase/server.ts`	Server components, API routes
Admin	`lib/supabase/server.ts`	Trusted server operations, such as verified webhooks (bypasses RLS)

Folder Structure

app/                    # Pages + API routes
├── page.tsx            # Landing page
├── dashboard/          # Protected pages
└── api/                # Backend endpoints

lib/                    # Business logic
├── stripe.ts           # Payment helpers
├── resend.tsx          # Email templates
└── supabase/           # Auth clients + database queries

components/             # Shared UI
emails/                 # Transactional email templates
docs/                   # Generated guide reference, not app routes

The Ghoststack guides are hosted separately, with a generated Markdown reference copy in docs/. A documentation website is an optional feature you can add to your own app.

Prompt: Understand a Flow

I want to understand how [FEATURE] works.

Trace the flow from user action to database.
Show me which files are involved and how they connect, using the actual code.
Explain unfamiliar terms and give me one example to follow. Do not edit files.

On this page