How it works
One package, many reactors
Capsium splits content management into two clean halves: a portable package format, and reactors that serve it. Here is how the pieces fit together.
Concepts
Four ideas, one architecture
- Capsium package
- A single portable file — extension .cap, MIME type application/vnd.capsium.package — that bundles content, data, and configuration into a checksummed ZIP archive.
- Package filesystem
- Inside the package, content and data live in an immutable, layered filesystem. Layers stack predictably, and nothing is ever mutated in place.
- Reactor
- Any runtime that reads a Capsium package and serves it: the Ruby reactor, the nginx/OpenResty Lua reactor, the browser extension, or the service worker.
- Activation
- The moment a reactor loads a package: it verifies checksums, mounts the layered filesystem, and starts answering the routes declared in routes.json.
Inside a package
Anatomy of a .cap file
A Capsium package is a ZIP archive with a rigorous structure. You hand-write metadata.json and fill content/; the packager generates the rest. Click any entry to explore it.
metadata.json
The one file you always write yourself: package name, version, description, license, repository, dependencies, and a readOnly flag.
Design principles
Principles from the standard
The CC 62001 draft standard defines the principles every Capsium package and reactor follows.
Ease of use
Creating, packing, and serving a package takes a handful of CLI commands.
Cross-platform deployment
The same .cap file runs on every reactor, from nginx to the browser.
Static nature
Packages are plain files — no databases, no server-side runtime required.
Size efficiency
ZIP compression and a lean structure keep packages small and fast to transfer.
Integrity
SHA-256 checksums for every file let reactors detect any tampering.
Self-containment
Content, data, routes, and metadata travel together in one artifact.
Versioning
Every package declares its version, making upgrades explicit and auditable.
Dependencies
Packages declare what they depend on, so reactors can resolve stacks of content.
Immutable layered filesystem
Packages mount as read-only layers; changes come from new versions, never edits.
Deployment-API compatibility
A stable contract between packages and reactors across the whole ecosystem.