Architecture

Position

WiseWig is an AI-native website framework that is opinionated about content safety, editing behavior, agent capabilities, and the site runtime. Astro is the supported theme and customer-site renderer for v1. React powers the editor overlay and management interfaces. Tailwind is optional.

It requires typed component contracts, structured documents, explicit placement/structure policy, immutable publish versions, authorization, and a shared command service for UI, API, CLI, and MCP. Pages and components contribute semantic AI context; core and plugin packages contribute MCP tools, resources, and prompts. It does not require Tailwind, a bundled model provider, or a particular database outside a chosen hosting adapter.

WiseWig is open-source and self-hostable. A managed deployment uses the same framework contracts; it is not a second rendering or content system. See the hosting model.

Rendering

Astro is required for themes in v1 because it fits the public-site profile: server-rendered HTML, edge caching, and isolated client islands. This is a product decision, not a claim that another renderer is impossible later.

@wise-wig/runtime owns request, session, authorization, document, asset, and render-decision contracts. The renderer-adapter type remains an internal seam only; it is not a public compatibility promise. The Morning Bell example is the reference Astro implementation.

Components and custom work

Built-in WiseWig components own nearly all of the static-versus-editor complexity: server rendering, edit metadata, inline-field behavior, selection outlines, structural policies, variants, placement, migrations, and validation. Theme authors should normally compose and style these components rather than rebuild editing mechanics.

When a built-in component does not fit, a developer may create a custom Astro component with defineComponent(). Custom components must still provide the same content schema, editor configuration, placement policy, migrations, and a single public/edit render path. They may choose to expose no editable fields at all. This is the escape hatch; it does not permit arbitrary client HTML editing or bypass framework authorization/versioning.

Themes

A developer-owned theme provides:

• semantic appearance tokens (color roles, typography, and shape);
• a layout slot manifest;
• components that render typed content into approved layouts;
• optional build hints.

Appearance and layout have separate ownership. Themes decide how semantic roles look: canvas, surfaces, text, actions, font families, the type scale, weights, line heights, and radii. Components decide geometry: markup, grid/flex placement, order, alignment, responsive breakpoints, and approved layout variants. Content supplies only schema-validated values. See Theme appearance and component layout for the complete token contract.

Theme build hints permit Tailwind content globs and safelists, but are optional. A theme may use regular CSS, CSS Modules, Tailwind, Panda, or another styling strategy. All of them consume the same semantic roles. The WiseWig runtime never parses or persists arbitrary class strings as customer content.

Request path

1. A public cache miss resolves a verified hostname to a tenant/site through D1, then serves the published version through edge caching; a cache hit avoids control-plane work.
2. A preview or edit request validates the session and site permission before it reads a draft.
3. The renderer adapter receives a RenderMode, typed document, and selected theme.
4. Edit mode adds component metadata and mounts a small React overlay; the page component itself remains server rendered.

See the public request path for the cache-first Cloudflare adapter contract.

Cloudflare adapter

TenantWorkspaceDO owns mutable per-agency workspace state, serialized writes, and immutable document versions in Durable Object SQLite. D1 remains the platform control plane for tenant/site/domain/membership routing; R2 owns asset bytes. The runtime interfaces make a different host implementation possible without changing theme/component contracts.

Managed Cloudflare hosting adds a Workers for Platforms dispatch boundary: one persisted user Worker per tenant, each exporting its own SQLite Durable Object namespace. The platform dispatch Worker selects that Worker only from a verified hostname lookup; caller-controlled routing values are ignored. The tenant isolation reference defines the topology, lifecycle states, and failure behavior.