How nikandr-surkov/ai-saas-starter works
This repository is a Next.js SaaS starter/demo whose main user journey is account access, credit-backed image generation, and subscription billing. The graph preserves the documented generation and billing stages plus the auth, ledger, and storage layers. The generation action and several billing modules are represented from the README and tree; their internal call wiring was not sampled, so only documented relationships are shown.
Main entry points: actions.ts Generation action · webhook.ts Webhook dispatch · db/index.ts PostgreSQL · credits/index.ts Credits ledger
Components 24
App experience
- App pages
src/app/(app) - Generation form
src/components/generate/generate-form.tsx - Dashboard
src/app/(app)/dashboard/page.tsx - Billing page
src/app/(app)/billing/page.tsx
Identity
- Auth endpoint
src/app/api/auth/[...all]/route.ts - Auth service
src/lib/auth/index.ts - Session helpers
src/lib/auth/session.ts
Image generation
- Generation action
src/app/(app)/generate/actions.ts - Rate limiting
src/lib/rate-limit.ts - AI image provider
src/lib/ai/provider.ts - Image storage
src/lib/ai/storage.ts - Dev image route
src/app/api/images/[file]/route.ts
Billing and credits
- Credits ledger
src/lib/credits/index.ts - Billing actions
src/lib/billing/actions.ts - Webhook endpoint
src/app/api/stripe/webhook/route.ts - Webhook dispatch
src/lib/billing/webhook.ts - Subscription sync
src/lib/billing/sync.ts - Plan configuration
src/config/plans.ts
Persistence
- PostgreSQL
src/db/index.ts
Other components
- User
- Stripe
- Image model
- Vercel Blob
- Email service
Connections 29
- User → Auth endpoint: signs in
- Auth endpoint → Auth service: delegates auth
- Auth service → PostgreSQL: persists sessions
- User → App pages: uses
- App pages → Session helpers: checks session
- User → Generation form: submits prompt
- Generation form → Generation action: submits generation
- Generation action → Rate limiting: rate limits
- Generation action → Credits ledger: spends credit
- Generation action → AI image provider: requests image
- AI image provider → Image model: generates image
- Generation action → Image storage: stores result
- Image storage → Vercel Blob: writes image
- Image storage → Dev image route: returns dev path
- Dev image route → PostgreSQL: checks ownership
- Dev image route → Session helpers: checks session
- Dashboard → Credits ledger: reads balance and history
- Credits ledger → PostgreSQL: reads and writes ledger
- Billing page → Plan configuration: renders plans
- User → Billing actions: starts checkout
- Billing actions → Stripe: creates checkout or portal
- Stripe → Webhook endpoint: sends events
- Webhook endpoint → Webhook dispatch: dispatches verified event
- Webhook dispatch → Subscription sync: syncs subscription
- Webhook dispatch → Credits ledger: grants top-up or plan credits
- Webhook dispatch → PostgreSQL: looks up customer and user
- Webhook dispatch → Email service: sends confirmation
- Subscription sync → Stripe: reads subscription state
- Subscription sync → PostgreSQL: updates subscription state