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:

• appearance tokens (color, typography, radius);
• a layout slot manifest;
• components that render typed content;
• optional build hints.

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. 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.