How wasp-lang/open-saas works
1. This repository is not a single app; it is an Open SaaS template ecosystem. The main pieces are the canonical starter app in template/, the public docs/blog site in template/blog, an applied reference instance in opensaas-sh/, and a Playwright test project in template/e2e-tests.
2. The core product architecture lives in template/app, which is a Wasp full-stack app. Wasp is the framework boundary that ties together frontend, backend operations, Prisma data modeling, auth, jobs, and deployment metadata from main.wasp and schema.prisma.
3. The frontend is organized by feature area rather than by route alone. src/client holds the shared shell and UI primitives, while domain screens live under src/auth, src/payment, src/user, src/file-upload, src/admin, and src/landing-page. This gives the UI a clear split between public marketing surfaces, authenticated user flows, and admin-only dashboards.
4. Backend logic is similarly domain-oriented. Each feature area has operations and helper modules that expose typed server actions to the client, with server-side scripts in src/server/scripts for bootstrapping and maintenance tasks. Shared utilities and cross-cutting types live in src/shared.
5. Persistence is centered on Prisma. The schema in schema.prisma plus the migration history define the database boundary, and the various feature modules consume that data model through Wasp-generated types and operations. The template also includes seeded data support for local setup and testing.
6. External integrations are first-class architectural boundaries. Payments can be wired through Stripe, Polar, or Lemon Squeezy; file uploads use AWS S3; analytics can use Plausible or Google Analytics; email flows are implemented for auth and app notifications. Webhooks sit on the server side and are the main ingress point from payment providers back into the app.
7. The public-facing marketing site and docs are a separate Astro app in template/blog. It is content-driven, with MDX docs under src/content/docs, shared Astro components, and media assets under src/assets and public/. This site is deployed independently from the Wasp app.
8. opensaas-sh/ is a maintained, branded instance of the template rather than the template itself. Its app_diff directory captures the delta from template/app, which makes the repository usable as both a starter kit and a live reference implementation. template-test/ uses the same pattern for testing template output.
9. The diff/patch tooling in tools/ and opensaas-sh/tools is a key repo subsystem. It supports generating, applying, and checking template diffs so the maintainers can keep the template, live site, and release artifacts in sync without hand-copying changes.
10. Automated verification and release are part of the architecture. template/e2e-tests runs Playwright against the generated app to validate core user journeys such as landing, auth, demo, and pricing. GitHub workflows handle template release, blog deployment, diff checking, and end-to-end validation.
11. In deployment terms, the app is designed for split hosting: the Wasp app deploys the client, server, and database-backed backend together, while the Astro blog is deployed separately. The repo’s config files and workflow scripts show that the project is optimized for repeatable template generation and multi-environment publishing rather than a single runtime.
Main entry points: main.wasp main.wasp · client Client shell · schema.prisma schema.prisma · payment Payments
Components 19
Template ecosystem
Canonical starter app, docs site, and verification project.
- main.wasp · Framework boundary wiring frontend, backend operations, auth, jobs, and deployment metadata.
template/app/main.wasp - schema.prisma · Database model and persistence boundary for the app.
template/app/schema.prisma - Client shell · Shared client app, layout, primitives, hooks, and common UI utilities.
template/app/src/client - Auth · Login, signup, password reset, verification, and signup-field customization.
template/app/src/auth - Payments · Pricing, checkout, processors, and provider-specific webhooks for Stripe, Polar, and Lemon Squeezy.
template/app/src/payment - File uploads · Upload flow, validation, S3 utilities, and server-side upload operations.
template/app/src/file-upload - Landing page · Public marketing surface with examples, features, testimonials, and hero content.
template/app/src/landing-page - Admin UI · Admin dashboards, tables, charts, and layout for operational oversight.
template/app/src/admin - Server scripts · Bootstrapping and maintenance jobs such as seeded data setup.
template/app/src/server/scripts - Shared code · Cross-cutting utilities and common types used by client and server features.
template/app/src/shared - Docs content · Content-driven docs and blog posts for the public site.
template/blog/src/content/docs - Blog components · Shared Astro components for navigation, banners, media, and page chrome.
template/blog/src/components - Assets · Images, videos, and public assets used by docs and blog posts.
template/blog/src/assets - E2E tests · Browser tests covering landing, auth, demo, and pricing journeys.
template/e2e-tests/tests
Reference instance
Branded live instance kept in sync via diffs.
- App diff · Branded instance changes captured as patch files against the canonical app.
opensaas-sh/app_diff - Reference blog · Maintained branded docs/blog instance corresponding to the public site.
opensaas-sh/blog
Automation
Release, deployment, and diff-check workflows.
- Workflows · Release, blog deployment, diff checks, and end-to-end validation automation.
.github/workflows
Diff tooling
Scripts for generating, applying, and validating template deltas.
- Patch tools · Scripts for generating, applying, and checking template diffs.
tools - Ref tools · Instance-specific diff tooling for keeping the branded reference aligned.
opensaas-sh/tools
Connections 33
- main.wasp → Client shell: loads UI · Defines the client/runtime boundary for the app.
- main.wasp → Auth: wires auth · Connects auth flows into the Wasp app.
- main.wasp → Payments: wires billing · Connects payment providers, checkout, and webhooks.
- main.wasp → File uploads: wires uploads · Adds file-upload capability to the app.
- main.wasp → Landing page: routes public UI · Exposes the marketing and landing experience.
- main.wasp → Admin UI: routes admin · Exposes admin dashboards and protected operations.
- main.wasp → Server scripts: schedules jobs · Includes server-side scripts and maintenance tasks.
- main.wasp → Shared code: shares types · Uses shared utilities and cross-cutting definitions.
- schema.prisma → Auth: models users · Backs auth-related data structures.
- schema.prisma → Payments: models billing · Persists payment and subscription state.
- schema.prisma → File uploads: models files · Persists upload metadata and storage references.
- Client shell → Auth: renders auth · Client pages and components for login and signup.
- Client shell → Payments: renders pricing · Client-side checkout and pricing surfaces.
- Client shell → File uploads: renders upload UI · Client-side upload experience and validation feedback.
- Landing page → Client shell: uses shell · Built on the shared client shell and UI primitives.
- Admin UI → Client shell: uses shell · Admin layouts and widgets reuse shared client foundations.
- Payments → schema.prisma: reads/writes · Billing operations update persisted account and subscription data.
- File uploads → schema.prisma: reads/writes · Upload operations persist file records.
- Server scripts → schema.prisma: seeds data · Bootstraps local and test data from the schema.
- Docs content → Blog components: composes · Docs pages are assembled from shared Astro components.
- Docs content → Assets: references media · Content embeds static media and banners.
- E2E tests → Landing page: verifies · Exercises the public landing experience.
- E2E tests → Auth: verifies · Covers authentication journeys.
- E2E tests → Payments: verifies · Covers demo and pricing flows.
- App diff → main.wasp: tracks delta · Encodes the branded instance as a patch against the canonical template.
- Reference blog → Docs content: mirrors content · Maintained as a branded counterpart to the template blog.
- Workflows → Docs content: deploys · Publishes the blog site through workflow automation.
- Workflows → E2E tests: runs · Executes end-to-end validation in CI.
- Workflows → App diff: checks diffs · Validates that reference changes stay synchronized.
- Workflows → main.wasp: releases template · Drives template release and publishing.
- Patch tools → App diff: generates/applies · Creates and applies template patch sets.
- Ref tools → App diff: checks/applies · Keeps the branded reference aligned with template changes.
- Ref tools → main.wasp: compares · Diffs the reference app against the canonical starter.