Most SaaS products die of architecture, not of demand. The team ships fast for
six weeks, then every new feature starts touching five files that nobody wants
to open. This is the setup we keep coming back to — boring in the right places,
strict where it pays off.

Start with the boundaries, not the framework

Before picking a router or a database, write down the boundaries. A boundary is
a place where one part of the system stops trusting another.

• UI renders state and collects intent. Nothing else.
• Core holds domain rules as plain TypeScript functions.
• Adapters talk to the outside world: database, mail, payments, storage.

When those three stay separate, swapping infrastructure is a Tuesday, not a
quarter. See the architecture notes for the full map.

Model your content as data, not as markup

Rich text is where products quietly accumulate debt. Store Markdown or an AST —
something you can query, diff and migrate — and treat HTML as an output format.

export interface Content {
  id: string;
  contentTypeId: string;
  title: string;
  markdown: string;
  metadata: Record<string, unknown>;
}

One content shape plus a content type beats six bespoke tables. The type
decides which metadata exists, which features are available and how the thing
gets published.

If you are writing a second editor, you are writing the same bugs twice.

Keep the runtime portable

Anything in core/ should run in a browser, in Node and on the edge. That
means no filesystem, no process access, and no Node-only dependencies.
Practically: use fetch, crypto.randomUUID() and the Web Streams API.

1. Pure domain logic in core/
2. Runtime access behind adapter interfaces
3. Framework code only at the edges

The payoff shows up the day you deploy to Cloudflare Workers
and nothing needs rewriting.

Ship SEO with the content, not after it

SEO is a content-quality problem with a deterministic checklist: one H1,
sane heading levels, a title that fits, a real meta description, alt text,
internal links. Compute it while the author types — no AI call required — and
it stops being a launch-week fire drill.

Conclusion

Choose the strict boundary over the clever abstraction, own your content model,
and keep the runtime portable. Next up: read the content types guide
and copy the editor into your own project.