control roomdocs/PURPOSE.md

Purpose

What this is for, and the finish line

Purpose

A modular SaaS template for serial founders. Ship fast, scale when it works.

This document is strategy and intent. Every sentence in it is about what the template is for, not about what it currently does. For the latter see README.md's status block, which as of 2026-09-11 says the template does not yet produce a deployable application.

The thesis

The template is not a product. It has exactly one customer, so it needs no product-market fit of its own. Its value is:

value  =  cost saved per attempt  x  number of attempts

That is the whole argument, and both terms are load-bearing.

docs/MEASUREMENT.md defines how the first term is counted, including what it deliberately does not capture - deciding what to build, debugging your own logic, and whether the product is any good. A template that makes a bad idea shippable in nine minutes has saved nothing, which is why this is a means rather than the goal.

Why a substrate rather than a team

There are three ways to build SaaS products repeatedly. Build each one from zero, which pays the same setup cost every time. Hire people, which converts money into throughput and adds coordination. Or build the shared substrate once, with AI doing most of the construction, and spend the saved time on the part that is genuinely different each time.

This project is the third. The substitution is capital for capability: instead of buying throughput per product, buy it once and amortise.

What should be left per product

If the substrate is right, a new product is three things:

  1. Characterising it - what it does, for whom, and why anyone pays.
  2. The front end - the part that is genuinely different every time.
  3. Spinning up the back end components it needs - not writing them.

Everything else is recurring work, and recurring work is what this template exists to delete. Auth, billing, deploy, migrations, health, secrets, observability, CI: each should be a decision rather than a project.

The test for any template feature: would you otherwise write this again for the next product? If no, it does not belong here.

The consequence that matters

Cheaper experiments mean more experiments. A validation that costs three days instead of three weeks can be run on ideas that would never justify three weeks, and most ideas do not. Lowering the cost of being wrong is how a portfolio of attempts beats a single bet.

And the same substrate that makes an attempt cheap makes a winner scalable, because the thing that scales is already underneath it rather than bolted on afterwards.

The two risks, stated plainly

Not product-market fit. These:

Attempt volume. The value multiplies by the number of attempts, so a substrate that saves three weeks and is followed by one product is a bad trade. Perfecting the template is the failure mode, not choosing to build it. The template is finished when it stops blocking products, not when it is good.

Surface area. Every component is maintained forever by one person, so template surface is a tax levied on every future attempt. There is an optimal size and it is smaller than "everything". This is why docs/PATHS.md makes the use case drive the template, and why four separate reviews of this repo found capability built before any caller existed.

The finish line

Stated by the owner on 2026-09-17, in answer to the observation that docs/PLANNING.md had no objective to optimise toward. Recorded close to his words, because an objective paraphrased is an objective negotiated.

Two halves, and the template is only half of it.

Ninety percent, from one click. The infrastructure common to ninety percent of SaaS products - not a minimum viable scaffold, but everything a SaaS needs from its smallest start through to increasingly larger scale, including the migrations between those stages. That last clause is the hard part and the one that distinguishes this from a starter kit: fly.io to Hetzner, one instance to many, sqlite to postgres, single-tenant to multi. adr-013's tiers exist because of it, and a stage transition nobody has walked is not supported, whatever the code says.

Nine percent more, from one interview. The other ninety percent is what is common at the product level rather than the infrastructure level - the audience, the voice, the design language, what the thing is for. Those are decisions every product needs and no product inherits, and today they are made ad hoc or not at all. Streamlining that is the second half: a short interview with an agent, after which the product has its own style and everything works.

So: one click for ninety, one interview for nine, and ninety-nine percent of a working product before a person writes anything. What remains is iteration toward exactly what was wanted, and that part is Claude Code and a founder.

The standard, which is not negotiable and is part of the objective

What ships is top-notch, and high standards are enforced by design rather than by discipline. The owner's own example is the 404: by design a 404 has to get an answer, and will get one, and the answer is aesthetic and intentful. Not because somebody remembered, but because the flow cannot produce a product without one.

That is why the seven always-needed surfaces are declared, why COMP-078 built error pages into the kit, and why COMP-096's live-surface walk judges a deployment rather than a repository. A defect a person would notice is a defect the flow should refuse to ship, and every time one reaches production it is evidence the flow is missing a gate rather than that somebody was careless.

The loop between the two halves

Building a specific product teaches the template, and that is a mechanism rather than a hope. Every real product exposes what the kit is missing - 2026-09-16 measured 108 files the one live product had never received, saas update having never been run as a writing operation, and error pages sitting in the kit for a week while the live site served raw JSON to a browser. None of that was visible from inside the template.

So what the template contains is driven by what building products reveals, and a product built without feeding findings back has been half wasted.

What this makes measurable

An objective this shape has numbers attached, which is the point of writing it down:

What it does not settle

The first goal is about a template and the second is about a process, and only the first has a repository. Where the interview lives, what it produces, and how its output reaches a scaffolded product are undecided - docs/PRODUCT-LIFECYCLE.md sketches the states and adr-009 records that generation is reproducible only as a record, not as a rerun.

Vision

Build multiple income streams through software products. Each product starts as an experiment, graduates to a business when validated.

Philosophy

Machete stage: Hack through the jungle to find gold. Speed matters, polish doesn't. But infrastructure is not polish - IaC from day one, because cleaning up click-ops later costs more than doing it right.

Highway stage: Pave a road to the gold you found. Invest in reliability, observability, and maintainability. The product now pays for its own development.

Bootstrap mentality: Products fund themselves. Infrastructure costs scale with revenue, not ambition.

On-prem as first-class: Some products need to run on the customer's hardware, or on your own. The intent is to support cloud, self-hosted VPS, and fully on-prem with local LLMs. Today the only supported target is fly.io, and even that has no fly.toml and no deploy command. saas new --target onprem and --target hetzner are accepted and do nothing. There is an Ollama adapter, which is the one on-prem piece that exists.

What This Template Supports

Read this as the intended product scope, not a capability list. The template has produced zero shipped products so far.

Principles

These are the rules the template is built to. Where the repo currently fails one, it says so, because a principle nobody checks is the failure mode described in docs/LESSONS.md.

An annotation carrying (planned) means the principle is an intention this repo does not satisfy yet. That is docs/FRONTMATTER.md's marker convention, and it is why this document is status: mixed rather than current: the principles are current policy, and four of the six annotations below describe something that does not exist. Until 2026-09-12 the honesty here lived only in hand written prose that a human read correctly and no gate could read at all.

  1. Explicit over implicit - Every stack choice is documented with alternatives and migration paths. Held for the stack. Not held for ADRs: eleven of thirteen decisions listed in docs/adr/README.md were never written up. (planned)
  2. One migration away - Never paint yourself into a corner. Always know the next step up. Documented in docs/MIGRATIONS.md, which is a design sketch. No migration has been scripted or performed. (planned)
  3. API-first - the template is a JSON API, and native mobile apps (iOS/Android) are intended to be first-class citizens of it. Two claims, two verdicts.

API-first: held. Seven JSON routes and no other surface. docs/adr/004-mobile-clients-and-api-versioning.md decides to keep it that way: the template ships no client code for any platform.

Native mobile first-class: not held (planned). Nothing a device needs exists. The routes are unversioned, so an app in an app store cannot be protected from a server change (contracts/api-versioning.md, CORE-036). No client is generated for any language (CORE-005). There are no refresh tokens, so a signed-in device is signed out again in thirty minutes (AUTH-007). There is no push (COMP-007), no OAuth provider of any kind (AUTH-001), no Apple provider (AUTH-005), and no way for a user to delete their own account, which Apple requires of any app that lets them create one (AUTH-004).

This annotation read "Held. The template is a JSON API and nothing else" until 2026-09-12. That is docs/LESSONS.md lesson 10: being API-only is not evidence that mobile is first-class, it is the absence of every client, and the wrong verdict is what kept the gap off every board for the life of the repo.

  1. Modular by design - Pick the components you need. Add more later. Don't ship bloat. Structurally held. Two components exist, so there is not much to pick from yet.
  2. On-prem capable - Everything can run on your own hardware if needed. Not held (planned). See above: there is no on-prem deployment path.
  3. Revenue from day one - Billing integration is not optional. Not held (planned). There are zero lines of billing code. backlog/components/billing.md.

Non-Goals