Skip to content

Under developmentMica is experimental and not ready for production. The API and the content format can still change, so read the release notes before you upgrade.Follow the releases.

Docs/Architecture

Build

Architecture

Understand how the model, repository, editor, and static build fit together.

9 min read

Mica follows one constraint: Git is the source of truth. Losing the Mica server must never mean losing website content.

The path

The model is a plain TypeScript module. Astro imports it to create typed collections. An Astro build also writes the model as data to .mica/schema.json.

Mica reads that model from the repository and generates its navigation, tables, and forms. A save lands in a draft workspace: your checkout, or the Git clone of the self-hosted editor. All editors see the drafts. In the local editor it is your checkout: each save writes files, and Publish makes a Git commit with your own git. In the self-hosted editor it is a Git clone on the data volume, and a draft is a file in that clone. Publish commits the changes that the editor chooses as one commit and pushes it over HTTPS. The push starts the existing site build.

The website never calls Mica. Mica never needs to know where the website is hosted. They meet in the repository.

The packages

  • @micacms/core defines fields, validation, serialization, and the files on disk.
  • @micacms/astro connects the model and content to the Astro Content Layer.
  • @micacms/runtime is the API server, with no authentication of its own. It also contains the file access for the local editor and the Git clone.
  • @micacms/editor-ui is the editing interface. It is not published: @micacms/editor and the image contain its build.
  • @micacms/auth-oidc is the OpenID Connect gate of the image. It is not published.

A website installs @micacms/core and @micacms/astro, and @micacms/editor as a development tool. These are the public packages. @micacms/runtime and @micacms/mcp are published too, because @micacms/editor needs them, but they are internal.

Two applications compose them. @micacms/editor is the local one: loopback only, no authentication, no user, no database, and it refuses an address on another machine. @micacms/self-hosted is the Docker image, behind OpenID Connect, with its own Git clone on the data volume. It fetches and fast-forwards on its own, and never merges. It pushes to any Git host over HTTPS. Git history shows the editor as author and Mica as committer.

See Choose how to run Mica for how to pick one.

Atomic changes

An entry can include JSON, rich text, and many media files. A publish writes the chosen changes in one commit or writes nothing. A stale revision gives a conflict response and leaves the editor's changes in the form. All languages of an entry are in the files of that entry, so they publish together.

Deliberate limits

Mica has no content API, GraphQL layer, media server, build webhook, page builder, or password system. These limits keep the public website independent and the editing system small.

Next

To run the self-hosted editor, go to Self-hosting.