templates.SaaSStarter/README.md

SaaS Starter — W4C project template

A W4C project template. Creating a project from it generates a private copy of this repository in your namespace and starts the Startup Creator agent, which drives the build from this brief.

This repository is deliberately a brief, not a finished app: it ships the product specification, the project metadata and the seed assets; the tech stack chosen in the creation dialog decides the scaffold. Read SPEC.md for the full product contract — roles, routes, data model, flows, functional and non-functional requirements, and the acceptance criteria the work is checked against. It is a multi-tenant SaaS: authentication, workspaces, billing, a tenant-scoped customer dashboard and a platform-operator back office.

What ships in this repository

Path	Purpose
README.md	This file: how the template is wired and how to work in the project.
SPEC.md	The product specification and acceptance criteria — the contract to build.
.gitignore	Default ignores for dependencies, build output, local secrets and editor/OS cruft.
.editorconfig	Shared editor defaults (UTF-8, LF, indentation) for the generated project.
.w4c/template.json	Template manifest: dialog fields, starter prompt, element list (templates only).
.w4c/project.json	Project metadata committed with the repository.
.w4c/diagrams/	Excalidraw architecture diagram.
.w4c/boards/roadmap.json	Board columns and the seed tasks for the build.
.w4c/workflows/	The CI workflow to import into the workflows module.

See .w4c/README.md for the full .w4c/ contract.

Stack

The creation dialog records the chosen stack (and its skill pair stack-* + stack-*-quality), the billing provider, the tenancy model and the auth provider. Scaffold with those skills and hold the work to their conventions and quality gates. The stack is not fixed here on purpose: the same brief is built on Next.js, Vue 3 + Quasar, Laravel, Phoenix, … without changing SPEC.md.

Build order

Work top-down, one layer at a time, and verify each layer before starting the next:

1. Scaffold the stack and get the empty shell running (install → dev server → commit).
2. Scope — routes and the data model from SPEC.md §3–§4, including organisationId and the shared tenant-scoping layer.
3. Auth + tenant scoping — signup, login, organisations, membership and roles, plus the cross-tenant isolation test before any dashboard work.
4. Dashboard shell scoped to the active organisation.
5. Billing + plan limits (mock provider first, then real), including signature-verified, idempotent webhooks and the server-side limit guard.
6. First product feature from the must-have list.
7. Admin back office, then quality — tests, CI, README quickstart, .env.example, accessibility.

The full rationale and the acceptance criteria live in SPEC.md §8–§9.

Working rules

• One concern per commit, conventional messages (feat:, fix:, chore:, docs:, test:).
• Tenant isolation is the top requirement: scope every query and mutation by organisationId server-side; never trust a client-supplied tenant id, and never rely on filtering in the UI.
• Authorize every mutation on the server; never only in the UI.
• Money is integer minor units (priceMinor), never floating point; format with the plan currency and en-US number formatting.
• Keep billing keys and provider secrets server-side only; verify webhook signatures and make webhook/checkout handling idempotent.
• Enforce plan limits server-side, not just in the UI.
• Never commit secrets — document them in .env.example instead.
• Keep docs/PLAN.md, the board and .w4c/project.json in sync as the project evolves.