Handbook
Documentation
Every page here is generated from the AstroBaaS repository, where the documentation is versioned with the commit it describes. Nothing is written twice.
Run it
From clone to a healthy deploy.
Overview
The tour: what it does, every environment variable, where data lives, schema migrations, architecture.
Reference deployment
nginx vhost and systemd unit with measured limits, and the post-deploy checklist of things that fail silently — each one paid for by a real incident.
Staging copies
One environment variable that keeps a clone of production out of the index, off the webhooks, and out of the analytics property.
Maintenance windows
Taking an install down honestly: 503 with Retry-After, never a 200 holding page, and the paths that stay open so you can turn it back off.
Upgrading
What a version bump touches, which migrations run at boot, and the order to do it in.
Storage drivers
A JSON file, SQLite, or libSQL/Turso — the same API behind all three, and when to move between them.
Security
The threat model, the hardening checklist for operators, and how to report a vulnerability.
Build on it
The API, and the two extension surfaces.
Headless integration
Pointing a storefront at the API: auth, envelopes, media_base, pagination, webhooks.
Plugin development
All three plugin kinds — bundled, declarative, shippable — the hook catalogue, routes, admin screens, namespaced storage, payment providers.
Theme development
Design tokens, slots, patterns, the customizer, and the naming rule that separates classes from custom properties.
The plugin platform
Why the boundaries sit where they sit: route confinement, the CSRF rule, what a plugin may never widen.
Architecture
How the process is put together, and which decisions the rest of the code is downstream of.
API stability
What is promised, what may change, and what a breaking change means here.
Commerce
The shop half.
Commerce
Products, variants, orders, shipping zones, coupons, tax classes — and money as integer cents, computed once.
Payments
Gateways, manual methods, webhook verification, and why a manual method can never shadow a gateway.
The optical vertical
The commercial module as a worked example of what a vertical is: prescriptions, frame geometry, fit tolerance.
Where it is going
What is planned, and the analysis behind it.
Execution plan
The build order: only what is actually being built, phase by phase, with a definition of done for each. This is the live plan.
The commerce plan
Every one of the 352 planned commerce items, split into the 166 that are free in the core and the 186 that are paid, with the rule that decides which is which. Nothing in it is built yet.
WordPress parity analysis
The 100 most-installed WordPress plugins as numbered capabilities, each scored against the actual code — including the eleven declined, with the architectural reason for each.
Proposals
Twenty-five costed proposals, each with what it breaks if built badly. The source the execution plan draws from.
Maturity phases
The older phased plan from prototype to production maturity. Kept because the phases it names are still how releases are cut.
The project
How it is licensed, governed, and released.
Licensing
The open-core reasoning in full — what GPL-3.0 does and does not stop, and the three viable shapes.
Contributing
How a change lands: the checks, the drivers, the verification discipline.
Contributor agreement
Signed once, covers everything after; what you keep, what you grant, and the honest case for declining.
Code of conduct
What is expected of everyone taking part, and who to contact.
Publishing releases
How a release is cut and pushed to npm, and what the tag triggers.
The API, at a glance
Five requests that show the shape. The whole surface is inHeadless integration, and it is machine-readable at/openapi.json on any install.
| Method | Path | What it gives you |
|---|---|---|
GET | /api/products?limit=24 | Catalogue page, with order caps and media_base in meta |
GET | /api/posts?kind=page | Content, filtered; drafts stay invisible without a session |
POST | /api/media/upload | Multipart; answers with dimensions, WebP variants, absolute URLs |
GET | /api/health/deep | 503 when anything essential is broken — assert it in deploys |
GET | /openapi.json | The whole surface, machine-readable, contract-tested in CI |