# The Fabrica — engineering documentation

This site is the reasoning behind **The Fabrica**, a production FastAPI +
Next.js SaaS foundation: what was built, what was rejected, what it costs,
and where the guarantees are narrower than the convenient phrasing.

It exists to answer one question before you spend anything:

> Is this engineered well enough that I would trust it as the foundation of
> my product?

## How these pages are produced

Every page under a section heading is **extracted from the product's own
documentation**, not written for this site. Passages are marked for
publication at the source, and each extraction is reviewed before it is
published.

That matters for one reason: a hand-written summary drifts. This site used
to carry three of them, and by the time they were retired one described the
credit ledger more accurately than the document it was summarising, and
another claimed file counts that had not been true for months. A copy nobody
regenerates is a claim nobody rechecks.

Each page also names the product version it describes:

```markdown
> Applies to **The Fabrica v0.1.2**. Documentation source: `1ee1bc9cb661`,
> including post-release documentation corrections.
```

Product version and documentation source are separate questions, and the
pages answer both. Documentation gets corrected after a release, so the text
here is newer than the release it describes — and the release it names is
only named when nothing in between changed how the product behaves. The
commit is there so a claim on this site can be tied to a specific state of
the product later.

## What is not here

The setup and deployment procedures, the compliance document set, the
scaffold templates, the operational how-tos and the troubleshooting
catalogue are not published. They are what a licence buys, and their absence
is enforced by tests rather than left to intention.

Nothing here is runnable, and none of it is open source — see
[`NOTICE.md`](https://github.com/webrot9/thefabrica-inspect/blob/main/NOTICE.md).

## Where to start

Three routes in, depending on what you are trying to decide.

**Is the hard part done properly?**
Read [Credits are a ledger, not a counter](/production/credits), then
[Webhook delivery is idempotent by construction](/production/webhook-delivery).
Both are concurrency problems that are cheap to get wrong and expensive to
discover in production. Then check the claim:
[the concurrency test and its output](/receipts/ledger-concurrency).

**Which decisions am I inheriting?**
[What is opinionated, and what is replaceable](/extending/opinionated-and-replaceable)
goes through every major choice — database, auth, billing, queue, frontend —
and says which are load-bearing, which are defaults, and what replacing each
one actually touches.

**Can I live in this codebase?**
[Architecture](/architecture) for the shape of it,
[the extension boundary](/extending/domain-boundary) for where your code
goes and precisely what that protects, and
[taking an update](/extending/taking-an-update) for what a release merge
actually does to a repository shaped like this one.

**Does it survive contact with reality?**
[What executing our own guide broke](/receipts/executing-the-guide) and
[two events, no delivery order](/receipts/paddle-delivery-order) are the
defects found by running the thing rather than describing it, and
[the threat model](/operating/security) states the residual risk rather than
stopping at the mitigations.

## An honest note on what you can verify

This is a vendor describing their own work. The code samples are real and
you can judge them directly. The test transcripts and the architecture
descriptions are reports about a repository you cannot see yet, and they
are worth what any such report is worth until you can read the source.

The reasoning is offered in a form you can argue with. If a decision here
looks wrong, it is worth asking about before buying.