Architecture, stack, key decisions and the quality gates DEV3 Rafterbase passed before release.
The engineering behind Rafterbase: optimistic versions with a conflict view, an environment promote that is one conditional update, idempotent scheduled publishing, scoped tokens, signed webhooks and a model migration that never destroys data, with the known limits written down.
The problem it solves
A content system looks finished once an editor can save a page and an API can return it. The problems come with two editors on one entry, a publish clicked twice, a scheduled post whose text changed after it was scheduled, a field type changed on a model with thousands of entries, a webhook URL that points at an internal address, or a staging environment promoted halfway. Each of these has to end in one safe state, and the people who extend the code must not be able to bring the bugs back by accident.
Architecture and approach
Rafterbase is a Next.js 16 application on MongoDB with a separate worker process. Everything that belongs to an organisation goes through a tenant plugin that fails closed, and nothing relies on multi-document transactions: each write is a conditional single-document update, a unique index acts as the lock, and a lost race compensates by releasing what it reserved.
Versions without overwrites
An entry save carries the version the editor loaded. A mismatch returns a conflict with the server's fields and a field diff instead of writing. Slugs are reserved through a unique index per content type, locale and environment, so two concurrent saves cannot both take the same slug. Restoring an old version creates a new draft; history is never rewritten.
Publishing that runs once
Publishing is a conditional update on the version being published, so five parallel publishes produce one publish, one delivery per webhook and four no-op successes. A scheduled action runs only if the entry is still at the version that was scheduled; otherwise it is marked stale and the editor is told.
Environments and models
Promoting staging to main is one conditional update of an alias, and the previous environment is kept as a backup. A model change produces a dry-run report of the values that cannot convert, and applying it moves those values into a shadow field kept for 30 days.
Tokens, webhooks and AI
Delivery, preview and management tokens are hashed, scoped to environments and rate limited. Webhook URLs and secrets are sealed at rest, payloads are signed with HMAC, outbound requests pin the resolved address and refuse private ranges, and a failing endpoint backs off and is disabled after 50 failures in a row. The AI panels are configured from one map file, send only the text being worked on after stripping tokens, webhook secrets and team members' details, and never apply a suggestion automatically. The product ships with the Gemini key blank.
Quality gates and results
The app has 542 tests plus 49 for the core, including race groups run against a real MongoDB for publishing, slugs, environment promotion and webhook delivery. The demo seed loads about 2,400 entries and 14,000 versions in well under a minute and a data check confirms every published entry against its content type. Known limits are written down: REST only with no GraphQL in this version, image renditions depend on the optional sharp package, delivery responses are cached for 60 seconds by default so heavy traffic needs a CDN, and there is no real-time co-editing.
Tech stack
| Area |
Technologies |
| Application |
Next.js 16 App Router, React 19, Tailwind CSS 4, Docs site with 12 guides |
| Content platform |
Spaces and environments, Content-type builder, Versions, schedules and locales, Delivery, Preview and Management APIs |
| Data and security |
MongoDB 6+, Fail-closed tenant plugin, Signed webhooks with DNS-pinned requests, Scoped API tokens |
| Quality |
Vitest unit and race tests, Headless smoke tests, Secret scan of the zip |
Inside the build
Headless CMS — Model it, write it, ship it anywhere, with real REST APIs.
Content modelling — Twelve field types, validations and migrations with a dry run.