Project Structure

SaaS Starter is a pnpm workspaces monorepo with clear separation between apps and shared packages.

app/
├── apps/
│   ├── api/           # Hono 4 REST + SSE API (Node 22)
│   └── web/           # Next.js 16 + React 19 frontend (serves docs at /docs)
├── packages/
│   ├── ai/            # 7-provider AI factory + RAG utilities
│   ├── analytics/     # PostHog + GA4 + Plausible adapters
│   ├── auth/          # Better Auth shared config
│   ├── cli/           # `pnpm cli` CLI tool (in monorepo)
│   ├── db/            # Drizzle ORM schema + migrations
│   ├── events/        # Typed in-process event bus
│   ├── mcp/           # Model Context Protocol server
│   ├── referrals/     # Referral program service
│   ├── roadmap/       # Public roadmap + voting service
│   ├── shared/        # Plan definitions, utilities, constants
│   ├── storage/       # S3/R2/local file storage adapters
│   ├── waitlist/      # Email waitlist service
│   └── webhooks/      # Outbound webhook dispatcher
├── content/
│   ├── blog/          # MDX blog posts
│   └── changelog/     # MDX changelog entries
├── docs/              # Markdown reference docs
└── scripts/           # Setup, seed, deploy helper scripts

API (apps/api)

• Framework: Hono 4.12 (ESM, Node 22)
• Pattern: Thin controllers → service layer → Drizzle ORM
• Middleware chain: rateLimit → requireAuth → requireOrgContext → zValidator
• Core routes (always on): /api/auth, /api/billing, /api/users, /api/gdpr, /api/sse, /api/admin, /api/analytics, …
• Optional routes are registered from apps/api/src/module-routes.ts using apps/api/src/generated/active-modules.generated.ts (run pnpm generate:active-modules after editing app.config.ts).

flowchart LR
  Web[NextWeb]
  API[HonoAPI]
  Mod[module-routes]
  Worker[BullMQWorker]
  DB[(Postgres)]
  Redis[(Redis)]
  Web --> API
  API --> Mod
  Mod --> DB
  Worker --> Redis
  Worker --> DB

Web (apps/web)

• Framework: Next.js 16 App Router
• UI: shadcn/ui + Tailwind CSS 4.2 + Framer Motion
• i18n: next-intl (en, es, fr, de, pt out of the box)
• Auth: Better Auth client

Database schema

All tables live in packages/db/src/schema/. Key tables:

| Table | Purpose | |---|---| | organization | Multi-tenant orgs | | subscription | Billing subscriptions (Stripe + Paddle) | | ai_usage | Per-org AI token tracking | | document_chunk | pgvector embeddings for RAG | | document_source | RAG document sources | | referrals | Referral tracking | | waitlist_entries | Email waitlist | | roadmap_items | Feature requests + votes |