Every website builder since WordPress has stored pages in a database. The template engine pulls rows from MySQL or Postgres, merges them with a theme, and spits out HTML on every request. Capuzzella takes a different approach: store every page as a plain HTML file on the filesystem. No database for content. No templating language. Just files.
It sounds almost too simple. But it turns out to be one of the best architectural decisions for an AI-powered website builder.
How Capuzzella Stores Pages
In Capuzzella, every page lives as an .html file inside a data/drafts/
directory. The URL structure maps directly to the file path: /blog/index.html is
literally data/drafts/blog/index.html on disk. When you publish, the file gets
copied to data/public/, assets get fingerprinted for cache-busting, and a sitemap
is regenerated. That's the entire publishing pipeline.
There's no ORM, no migration files, no schema to keep in sync. Reading a page is
fs.readFile. Saving a page is fs.writeFile. The simplicity is the point.
Why Databases Are a Poor Fit for AI-Edited Content
Traditional CMS platforms store page content as blobs in a database — often as serialized JSON or escaped HTML inside a text column. This creates a problem when an AI agent needs to edit a page: the agent has to go through an API layer, which has to deserialize the content, make changes, re-serialize, and write it back through another API call. Every step is a place where formatting breaks, entities get double-escaped, or structure is lost.
With Capuzzella, the AI reads and writes complete HTML files directly. The agent sees exactly what the browser sees. There's no translation layer, no proprietary block format to learn, no risk of corrupting a serialization boundary. HTML is the source of truth, and AI models already understand HTML extremely well.
The Database Tax
Databases come with real operational costs that most website builders quietly pass on to their users:
- Infrastructure complexity. You need a database server, connection pooling, backups, and monitoring. A filesystem needs a disk.
- Schema migrations. Every time the CMS updates its content model, existing data has to be migrated. HTML files don't have this problem — HTML is backwards-compatible by design.
- Vendor lock-in. Your content lives in a proprietary schema. Exporting it means
building a custom tool. With files, your backup strategy is
cp -r. - Performance overhead. Database-backed CMS platforms need caching layers (Redis, Varnish, CDN page rules) to achieve what static files give you for free: instant responses.
Capuzzella uses SQLite, but only for application state — user accounts, API keys, and scheduled publishes. The content itself never touches a database.
Static Files Make AI Editing Predictable
When an AI agent edits a database-backed page, the result depends on how the CMS renders its stored format. Gutenberg blocks, Contentful entries, Sanity documents — each has its own rendering pipeline that can introduce surprises between what the AI wrote and what the user sees.
With static HTML, what the AI writes is exactly what gets served. In Capuzzella's edit mode, the draft file is served directly to the browser with the Editor Panel injected alongside it. The user sees the real page, not a preview approximation. When they publish, that same file is what goes live. No render step. No "it looked different in the editor" moments.
Portability and Ownership
A Capuzzella site is a folder of HTML files. You can back it up with tar,
version it with Git, deploy it to any static host, or inspect it with a text editor.
Your content isn't trapped in a database dump that only one application can interpret.
As Hunter Leath at Archil writes, "AI models are changing this process because they have given us the first tools to easily work with unstructured data at scale without needing to first put it in a database." Static HTML files are the most direct expression of this idea applied to web content.
Where Databases Still Win
Files aren't the answer to everything. As Daniel Phiri points out, "filesystems are winning as an interface, databases are winning as a substrate." If you need full-text search across thousands of pages, concurrent multi-user editing, or complex relational queries, a database substrate makes sense.
But most websites — business sites, portfolios, blogs, landing pages — don't need any of that. They need fast page loads, easy backups, and content that the site owner actually controls. For these use cases, static HTML files are simpler, faster, and more durable than any database.