# wasp-lang/open-saas architecture

> Architecture diagram of the GitHub repository wasp-lang/open-saas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wasp-lang/open-saas
- Repository: https://github.com/wasp-lang/open-saas

## Overview

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: [`template/app/main.wasp`](https://github.com/wasp-lang/open-saas/blob/main/template/app/main.wasp) (main.wasp), [`template/app/src/client`](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/client) (Client shell), [`template/app/schema.prisma`](https://github.com/wasp-lang/open-saas/blob/main/template/app/schema.prisma) (schema.prisma), [`template/app/src/payment`](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/payment) (Payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_template["Template ecosystem"]
  node_template_app_main["main.wasp<br/>Wasp app config<br/>[main.wasp]"]
  node_template_app_schema["schema.prisma<br/>Prisma schema<br/>[schema.prisma]"]
  node_template_app_client["Client shell<br/>React UI shell"]
  node_template_app_auth["Auth"]
  node_template_app_payment["Payments<br/>billing integration"]
  node_template_app_uploads["File uploads<br/>storage integration"]
  node_template_app_landing["Landing page<br/>marketing UI"]
  node_template_app_admin["Admin UI<br/>dashboard UI"]
  node_template_app_server["Server scripts<br/>backend scripts"]
  node_template_app_shared["Shared code<br/>shared types"]
  node_template_blog_docs["Docs content<br/>Astro MDX content"]
  node_template_blog_components["Blog components<br/>Astro UI"]
  node_template_blog_assets["Assets<br/>static media"]
  node_template_e2e_tests["E2E tests<br/>Playwright suite"]
end

subgraph group_reference["Reference instance"]
  node_ref_app_diff["App diff<br/>template delta"]
  node_ref_blog["Reference blog<br/>Astro site"]
end

subgraph group_automation["Automation"]
  node_automation_workflows["Workflows<br/>GitHub Actions<br/>[workflows]"]
end

subgraph group_tooling["Diff tooling"]
  node_diff_tools["Patch tools<br/>shell tooling"]
  node_ref_tools["Ref tools<br/>shell tooling"]
end

node_template_app_main -->|"loads UI"| node_template_app_client
node_template_app_main -->|"wires auth"| node_template_app_auth
node_template_app_main -->|"wires billing"| node_template_app_payment
node_template_app_main -->|"wires uploads"| node_template_app_uploads
node_template_app_main -->|"routes public UI"| node_template_app_landing
node_template_app_main -->|"routes admin"| node_template_app_admin
node_template_app_main -->|"schedules jobs"| node_template_app_server
node_template_app_main -->|"shares types"| node_template_app_shared
node_template_app_schema -->|"models users"| node_template_app_auth
node_template_app_schema -->|"models billing"| node_template_app_payment
node_template_app_schema -->|"models files"| node_template_app_uploads
node_template_app_client -->|"renders auth"| node_template_app_auth
node_template_app_client -->|"renders pricing"| node_template_app_payment
node_template_app_client -->|"renders upload UI"| node_template_app_uploads
node_template_app_landing -->|"uses shell"| node_template_app_client
node_template_app_admin -->|"uses shell"| node_template_app_client
node_template_app_payment -->|"reads/writes"| node_template_app_schema
node_template_app_uploads -->|"reads/writes"| node_template_app_schema
node_template_app_server -->|"seeds data"| node_template_app_schema
node_template_blog_docs -->|"composes"| node_template_blog_components
node_template_blog_docs -->|"references media"| node_template_blog_assets
node_template_e2e_tests -->|"verifies"| node_template_app_landing
node_template_e2e_tests -->|"verifies"| node_template_app_auth
node_template_e2e_tests -->|"verifies"| node_template_app_payment
node_ref_app_diff -.->|"tracks delta"| node_template_app_main
node_ref_blog -.->|"mirrors content"| node_template_blog_docs
node_automation_workflows -->|"deploys"| node_template_blog_docs
node_automation_workflows -->|"runs"| node_template_e2e_tests
node_automation_workflows -->|"checks diffs"| node_ref_app_diff
node_automation_workflows -->|"releases template"| node_template_app_main
node_diff_tools -->|"generates/applies"| node_ref_app_diff
node_ref_tools -->|"checks/applies"| node_ref_app_diff
node_ref_tools -->|"compares"| node_template_app_main

click node_template_app_main "https://github.com/wasp-lang/open-saas/blob/main/template/app/main.wasp"
click node_template_app_schema "https://github.com/wasp-lang/open-saas/blob/main/template/app/schema.prisma"
click node_template_app_client "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/client"
click node_template_app_auth "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/auth"
click node_template_app_payment "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/payment"
click node_template_app_uploads "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/file-upload"
click node_template_app_landing "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/landing-page"
click node_template_app_admin "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/admin"
click node_template_app_server "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/server/scripts"
click node_template_app_shared "https://github.com/wasp-lang/open-saas/tree/main/template/app/src/shared"
click node_template_blog_docs "https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/content/docs"
click node_template_blog_components "https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/components"
click node_template_blog_assets "https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/assets"
click node_template_e2e_tests "https://github.com/wasp-lang/open-saas/tree/main/template/e2e-tests/tests"
click node_ref_app_diff "https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/app_diff"
click node_ref_blog "https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/blog"
click node_automation_workflows "https://github.com/wasp-lang/open-saas/blob/main/.github/workflows"
click node_diff_tools "https://github.com/wasp-lang/open-saas/tree/main/tools"
click node_ref_tools "https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_template_app_main,node_template_app_schema,node_template_app_client,node_template_app_auth,node_template_app_payment,node_template_app_uploads,node_template_app_landing,node_template_app_admin,node_template_app_server,node_template_app_shared,node_template_blog_docs,node_template_blog_components,node_template_blog_assets,node_template_e2e_tests toneBlue
class node_ref_app_diff,node_ref_blog toneAmber
class node_automation_workflows toneMint
class node_diff_tools,node_ref_tools toneRose
```

## Components

### Template ecosystem

Canonical starter app, docs site, and verification project.

- [main.wasp](https://github.com/wasp-lang/open-saas/blob/main/template/app/main.wasp): Wasp app config · Framework boundary wiring frontend, backend operations, auth, jobs, and deployment metadata. · `template/app/main.wasp`
- [schema.prisma](https://github.com/wasp-lang/open-saas/blob/main/template/app/schema.prisma): Prisma schema · Database model and persistence boundary for the app. · `template/app/schema.prisma`
- [Client shell](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/client): React UI shell · Shared client app, layout, primitives, hooks, and common UI utilities. · `template/app/src/client`
- [Auth](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/auth): auth flow · Login, signup, password reset, verification, and signup-field customization. · `template/app/src/auth`
- [Payments](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/payment): billing integration · Pricing, checkout, processors, and provider-specific webhooks for Stripe, Polar, and Lemon Squeezy. · `template/app/src/payment`
- [File uploads](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/file-upload): storage integration · Upload flow, validation, S3 utilities, and server-side upload operations. · `template/app/src/file-upload`
- [Landing page](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/landing-page): marketing UI · Public marketing surface with examples, features, testimonials, and hero content. · `template/app/src/landing-page`
- [Admin UI](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/admin): dashboard UI · Admin dashboards, tables, charts, and layout for operational oversight. · `template/app/src/admin`
- [Server scripts](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/server/scripts): backend scripts · Bootstrapping and maintenance jobs such as seeded data setup. · `template/app/src/server/scripts`
- [Shared code](https://github.com/wasp-lang/open-saas/tree/main/template/app/src/shared): shared types · Cross-cutting utilities and common types used by client and server features. · `template/app/src/shared`
- [Docs content](https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/content/docs): Astro MDX content · Content-driven docs and blog posts for the public site. · `template/blog/src/content/docs`
- [Blog components](https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/components): Astro UI · Shared Astro components for navigation, banners, media, and page chrome. · `template/blog/src/components`
- [Assets](https://github.com/wasp-lang/open-saas/tree/main/template/blog/src/assets): static media · Images, videos, and public assets used by docs and blog posts. · `template/blog/src/assets`
- [E2E tests](https://github.com/wasp-lang/open-saas/tree/main/template/e2e-tests/tests): Playwright suite · 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](https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/app_diff): template delta · Branded instance changes captured as patch files against the canonical app. · `opensaas-sh/app_diff`
- [Reference blog](https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/blog): Astro site · Maintained branded docs/blog instance corresponding to the public site. · `opensaas-sh/blog`

### Automation

Release, deployment, and diff-check workflows.

- [Workflows](https://github.com/wasp-lang/open-saas/blob/main/.github/workflows): GitHub Actions · 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](https://github.com/wasp-lang/open-saas/tree/main/tools): shell tooling · Scripts for generating, applying, and checking template diffs. · `tools`
- [Ref tools](https://github.com/wasp-lang/open-saas/tree/main/opensaas-sh/tools): shell tooling · Instance-specific diff tooling for keeping the branded reference aligned. · `opensaas-sh/tools`

## Connections

- 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.
