# corebunch/instatic architecture

> Architecture diagram of the GitHub repository corebunch/instatic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corebunch/instatic
- Repository: https://github.com/corebunch/instatic

## Overview

1. **This is a single-product monorepo centered on one Bun server.**  
   The repo splits into three big runtime surfaces: `src/server` for backend APIs and publishing, `src/admin` for the React admin/editor app, and `src/core` for shared domain logic and schemas. Built-in editor modules live in `src/modules`, while reusable UI primitives live in `src/ui`.

2. **The main architectural boundary is “admin/editor” vs “public site.”**  
   The admin app is a Vite-built React SPA that talks to the Bun server through typed persistence/API clients. The public site is not served from the editor runtime; it is generated by the publisher into static artifacts and then served by the server/public router with a small dynamic runtime only where needed.

3. **`src/core` is the domain layer and source of truth.**  
   It contains the canonical models and schemas for content, page trees, layouts, forms, fonts, framework tokens, module engine, templates, loops, site runtime, site import, visual components, plugins, and persistence contracts. Most server handlers and admin views depend on these core types rather than duplicating business rules.

4. **`src/server` is a modular backend with a hand-written router.**  
   `server/index.ts`, `server/router.ts`, and `server/http.ts` anchor the request pipeline. Feature-specific handlers live under `server/handlers/cms`, `server/ai/handlers`, and other top-level subsystems. The server uses repository modules (`server/repositories`) to isolate DB access and keep request logic separate from persistence.

5. **Persistence flows through a shared DB abstraction with SQLite/Postgres parity.**  
   `server/db` selects the concrete client and runs dialect-specific migrations, while repositories encapsulate tables like users, sessions, media, plugins, site settings, publish state, and data rows. The repo emphasizes schema validation at boundaries via TypeBox and shared validation helpers in `src/core/persistence`.

6. **The admin app is organized as workspaces, not a generic dashboard.**  
   Major user surfaces are `src/admin/pages/site`, `content`, `data`, `media`, `plugins`, `users`, `ai`, and `dashboard`. Each workspace owns its own state slices, hooks, panels, dialogs, and canvas/editor components, with shared chrome in `src/admin/shared` and routing in `src/admin/router.tsx`.

7. **The site editor is a canvas-driven state machine.**  
   `src/admin/pages/site` contains the visual canvas, inspector panels, tree explorer, module picker, toolbar, preview, and editor store. The store is split into slices for selection, clipboard, layouts, settings, site data, style rules, visual components, and undo/redo. This is the core editing subsystem for pages, layouts, templates, and reusable components.

8. **Built-in modules provide the editor’s composable block system.**  
   `src/modules/base` defines standard blocks such as text, button, image, link, container, forms, list, video, SVG, outlet, slot instance/outlet, and visual component refs. These modules feed the module engine in `src/core/module-engine` and the editor canvas in `src/admin/pages/site/canvas`, so module rendering and editing stay aligned.

9. **Publishing is a separate pipeline that converts editor state into clean output.**  
   The publisher in `src/core/publisher` and `server/publish` turns site state into semantic HTML, compact CSS, static assets, and route-aware dynamic holes. It includes render caching, loop rendering, CSS collection, CSP planning, asset bundling, and static artifact management. This is the key public-site data flow: content and design state in, files on disk out.

10. **Dynamic public requests are minimized and cached aggressively.**  
   `server/publish/publicRouter.ts`, `server/publish/renderCache.ts`, and related runtime helpers serve prebuilt pages and only fall back to live rendering for truly dynamic paths. The README’s “static by default” promise is reflected in the architecture: publish invalidates caches, swaps artifacts atomically, and keeps the public runtime small.

11. **The plugin system is a sandboxed runtime with explicit host boundaries.**  
   Plugins are packaged and loaded through `src/core/plugins` and `server/plugins`, then executed in QuickJS-WASM under `server/plugins/quickjs` and `server/plugins/host`. The host/worker split, message protocol, and capability gates keep plugins isolated from filesystem, secrets, and unrestricted network access unless permissions are granted.

12. **Plugin capabilities are first-class across the product.**  
   Plugins can contribute admin pages, panels, dashboard widgets, canvas overlays, routes, media storage adapters, schedules, loops, and lifecycle hooks. The plugin SDK in `src/core/plugin-sdk` defines the manifest/builders/types used by plugin authors, while host registries and event broadcasters wire installed plugins into the rest of the system.

13. **AI is a separate subsystem with provider drivers, tool runtime, and persistence.**  
   `server/ai` includes provider adapters for Anthropic, OpenAI, OpenRouter, and Ollama, plus streaming/tool-loop infrastructure and audit/conversation/credential stores. On the admin side, `src/admin/pages/site/agent` and `src/admin/pages/content/agent` expose agent panels and bridges that let the assistant modify real site/content state through controlled tools.

14. **Content, data, forms, and loops all share the same underlying row model.**  
   `src/core/data`, `src/core/forms`, `src/core/loops`, and `server/handlers/cms/data` show a common pattern: structured tables and rows are the canonical content substrate. Pages/posts/custom collections/forms feed the same storage model, and loops render collections back onto pages through defined sources and templates.

15. **Media and files are treated as a managed subsystem, not raw uploads.**  
   `server/handlers/cms/media*`, `server/repositories/media*`, and `src/admin/pages/media` cover upload dispatch/execution, folders, variants, storage adapters, replacements, and usage tracking. The design supports local disk by default but leaves a clear adapter boundary for alternate storage backends.

16. **Security and operational concerns are built into the architecture.**  
   Authentication includes sessions, MFA/TOTP, lockout, rate limiting, and step-up policies in `server/auth`. Secrets are encrypted at rest, capabilities gate sensitive routes, and architecture tests in `src/__tests__/architecture` enforce invariants like sandbox isolation, publish behavior, and dependency boundaries. Deployment is container-friendly via Bun, Docker, Compose, and documented Railway/Caddy/VPS flows.

Main entry points: [`src/core`](https://github.com/corebunch/instatic/tree/main/src/core) (Core domain), [`src/admin/router.tsx`](https://github.com/corebunch/instatic/blob/main/src/admin/router.tsx) (Admin router), [`src/ui/components`](https://github.com/corebunch/instatic/tree/main/src/ui/components) (UI kit), [`server/router.ts`](https://github.com/corebunch/instatic/blob/main/server/router.ts) (Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_server["Server"]
  node_server_entry["Server entry<br/>bun server<br/>[index.ts]"]
  node_server_router["Router<br/>[router.ts]"]
  node_server_cms["CMS handlers<br/>feature handlers<br/>[index.ts]"]
  node_server_db[("DB layer<br/>sqlite/pg db<br/>[index.ts]")]
  node_server_repos["Repositories<br/>persistence adapters"]
  node_server_publish["Publisher<br/>publish pipeline<br/>[publishSite.ts]"]
  node_server_public["Public router<br/>public serving<br/>[publicRouter.ts]"]
  node_server_auth["Auth<br/>security<br/>[security.ts]"]
  node_server_plugins["Plugin host<br/>sandbox runtime<br/>[runtime.ts]"]
  node_server_ai["AI runtime<br/>assistant subsystem<br/>[index.ts]"]
end

subgraph group_group_core["Core"]
  node_core_domain["Core domain<br/>models/schemas"]
  node_core_page_tree["Page tree<br/>tree model<br/>[index.ts]"]
  node_core_publisher["Core publisher<br/>render pipeline<br/>[index.ts]"]
  node_core_persistence["Persistence contracts<br/>typebox contracts<br/>[index.ts]"]
  node_core_pluginsdk["Plugin SDK<br/>plugin contracts<br/>[index.ts]"]
  node_core_siteimport["Site import<br/>ingest pipeline<br/>[index.ts]"]
  node_core_site_runtime["Site runtime<br/>runtime contracts<br/>[index.ts]"]
end

subgraph group_group_admin["Admin"]
  node_admin_router["Admin router<br/>spa routing<br/>[router.tsx]"]
  node_admin_site["Site editor<br/>canvas workspace<br/>[SitePage.tsx]"]
  node_admin_content["Content workspace<br/>editor workspace<br/>[ContentPage.tsx]"]
  node_admin_data["Data workspace<br/>table workspace<br/>[DataPage.tsx]"]
  node_admin_media["Media workspace<br/>asset workspace<br/>[MediaPage.tsx]"]
  node_admin_plugins["Plugins page<br/>plugin admin<br/>[PluginsPage.tsx]"]
end

subgraph group_group_shared["Shared UI"]
  node_admin_sharedui["UI kit<br/>primitives"]
  node_modules_base["Base modules<br/>editor blocks"]
end

subgraph group_group_runtime["Public runtime"]
  node_public_artifacts["Static artifacts<br/>generated output<br/>[staticArtefact.ts]"]
end

node_server_entry -->|"boots"| node_server_router
node_server_router -->|"dispatches"| node_server_cms
node_server_router -->|"serves"| node_server_public
node_server_router -->|"gates"| node_server_auth
node_server_cms -->|"uses"| node_server_repos
node_server_repos -->|"queries"| node_server_db
node_server_cms -->|"validates"| node_core_persistence
node_server_cms -->|"depends on"| node_core_domain
node_server_publish -->|"renders with"| node_core_publisher
node_server_publish -->|"reads"| node_server_repos
node_server_publish -->|"writes"| node_public_artifacts
node_server_public -->|"serves"| node_public_artifacts
node_server_public -.->|"falls back to"| node_server_publish
node_server_plugins -->|"implements"| node_core_pluginsdk
node_server_plugins -->|"stores"| node_server_repos
node_server_ai -->|"uses"| node_core_domain
node_admin_router -->|"routes to"| node_admin_site
node_admin_router -->|"routes to"| node_admin_content
node_admin_router -->|"routes to"| node_admin_data
node_admin_router -->|"routes to"| node_admin_media
node_admin_router -->|"routes to"| node_admin_plugins
node_admin_site -->|"models"| node_core_domain
node_admin_site -->|"renders"| node_modules_base
node_admin_content -->|"models"| node_core_domain
node_admin_data -->|"models"| node_core_domain
node_admin_media -->|"models"| node_core_domain
node_admin_plugins -->|"configures"| node_core_pluginsdk
node_admin_site -->|"uses"| node_admin_sharedui
node_admin_content -->|"uses"| node_admin_sharedui
node_admin_data -->|"uses"| node_admin_sharedui
node_admin_media -->|"uses"| node_admin_sharedui
node_admin_plugins -->|"uses"| node_admin_sharedui
node_core_page_tree -->|"defines"| node_core_domain
node_core_publisher -->|"renders"| node_core_page_tree
node_core_siteimport -->|"ingests into"| node_core_domain
node_core_site_runtime -->|"feeds"| node_core_publisher
node_modules_base -->|"registers"| node_core_domain

click node_server_entry "https://github.com/corebunch/instatic/blob/main/server/index.ts"
click node_server_router "https://github.com/corebunch/instatic/blob/main/server/router.ts"
click node_server_cms "https://github.com/corebunch/instatic/blob/main/server/handlers/cms/index.ts"
click node_server_db "https://github.com/corebunch/instatic/blob/main/server/db/index.ts"
click node_server_repos "https://github.com/corebunch/instatic/tree/main/server/repositories"
click node_server_publish "https://github.com/corebunch/instatic/blob/main/server/publish/publishSite.ts"
click node_server_public "https://github.com/corebunch/instatic/blob/main/server/publish/publicRouter.ts"
click node_server_auth "https://github.com/corebunch/instatic/blob/main/server/auth/security.ts"
click node_server_plugins "https://github.com/corebunch/instatic/blob/main/server/plugins/runtime.ts"
click node_server_ai "https://github.com/corebunch/instatic/blob/main/server/ai/runtime/index.ts"
click node_core_domain "https://github.com/corebunch/instatic/tree/main/src/core"
click node_core_page_tree "https://github.com/corebunch/instatic/blob/main/src/core/page-tree/index.ts"
click node_core_publisher "https://github.com/corebunch/instatic/blob/main/src/core/publisher/index.ts"
click node_core_persistence "https://github.com/corebunch/instatic/blob/main/src/core/persistence/index.ts"
click node_core_pluginsdk "https://github.com/corebunch/instatic/blob/main/src/core/plugin-sdk/index.ts"
click node_core_siteimport "https://github.com/corebunch/instatic/blob/main/src/core/siteImport/index.ts"
click node_core_site_runtime "https://github.com/corebunch/instatic/blob/main/src/core/site-runtime/index.ts"
click node_admin_router "https://github.com/corebunch/instatic/blob/main/src/admin/router.tsx"
click node_admin_site "https://github.com/corebunch/instatic/blob/main/src/admin/pages/site/SitePage.tsx"
click node_admin_content "https://github.com/corebunch/instatic/blob/main/src/admin/pages/content/ContentPage.tsx"
click node_admin_data "https://github.com/corebunch/instatic/blob/main/src/admin/pages/data/DataPage.tsx"
click node_admin_media "https://github.com/corebunch/instatic/blob/main/src/admin/pages/media/MediaPage.tsx"
click node_admin_plugins "https://github.com/corebunch/instatic/blob/main/src/admin/pages/plugins/PluginsPage.tsx"
click node_admin_sharedui "https://github.com/corebunch/instatic/tree/main/src/ui/components"
click node_modules_base "https://github.com/corebunch/instatic/tree/main/src/modules/base"
click node_public_artifacts "https://github.com/corebunch/instatic/blob/main/server/publish/staticArtefact.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_server_router,node_server_cms,node_server_db,node_server_repos,node_server_publish,node_server_public,node_server_auth,node_server_plugins,node_server_ai toneBlue
class node_core_domain,node_core_page_tree,node_core_publisher,node_core_persistence,node_core_pluginsdk,node_core_siteimport,node_core_site_runtime toneAmber
class node_admin_router,node_admin_site,node_admin_content,node_admin_data,node_admin_media,node_admin_plugins toneMint
class node_admin_sharedui,node_modules_base toneRose
class node_public_artifacts toneIndigo
```

## Components

### Server

Bun backend, routing, persistence, publishing, auth, plugins, AI, and runtime serving.

- [Server entry](https://github.com/corebunch/instatic/blob/main/server/index.ts): bun server · Bootstraps the Bun process, config, HTTP pipeline, and top-level router. · `server/index.ts`
- [Router](https://github.com/corebunch/instatic/blob/main/server/router.ts): http router · Hand-written request router and HTTP dispatch layer for CMS, public, and utility routes. · `server/router.ts`
- [CMS handlers](https://github.com/corebunch/instatic/blob/main/server/handlers/cms/index.ts): feature handlers · Backend API surface for site, content, media, data, users, publish, forms, and admin operations. · `server/handlers/cms/index.ts`
- [DB layer](https://github.com/corebunch/instatic/blob/main/server/db/index.ts): sqlite/pg db · Database client selection, dialect-specific migrations, and low-level SQL access. · `server/db/index.ts`
- [Repositories](https://github.com/corebunch/instatic/tree/main/server/repositories): persistence adapters · Table-oriented persistence modules for users, sessions, media, plugins, publish state, site, and data rows. · `server/repositories`
- [Publisher](https://github.com/corebunch/instatic/blob/main/server/publish/publishSite.ts): publish pipeline · Converts site state into HTML, CSS, assets, caches, and static artefacts for the public site. · `server/publish/publishSite.ts`
- [Public router](https://github.com/corebunch/instatic/blob/main/server/publish/publicRouter.ts): public serving · Serves published artefacts and performs the small dynamic fallback runtime when needed. · `server/publish/publicRouter.ts`
- [Auth](https://github.com/corebunch/instatic/blob/main/server/auth/security.ts): security · Sessions, MFA, lockout, rate limiting, step-up policies, and security primitives. · `server/auth/security.ts`
- [Plugin host](https://github.com/corebunch/instatic/blob/main/server/plugins/runtime.ts): sandbox runtime · Plugin packaging, host boundary, QuickJS execution, protocol, worker pool, and capability gates. · `server/plugins/runtime.ts`
- [AI runtime](https://github.com/corebunch/instatic/blob/main/server/ai/runtime/index.ts): assistant subsystem · Provider adapters, tool loop, streaming transport, conversation/audit stores, and server AI handlers. · `server/ai/runtime/index.ts`

### Core

Shared domain models, schemas, publisher logic, plugin SDK, import/export, and site runtime contracts.

- [Core domain](https://github.com/corebunch/instatic/tree/main/src/core): models/schemas · Canonical models and schemas for content, pages, layouts, forms, templates, loops, plugins, and persistence. · `src/core`
- [Page tree](https://github.com/corebunch/instatic/blob/main/src/core/page-tree/index.ts): tree model · Page, layout, selector, condition, mutation, and explorer-path logic for the site document model. · `src/core/page-tree/index.ts`
- [Core publisher](https://github.com/corebunch/instatic/blob/main/src/core/publisher/index.ts): render pipeline · Shared rendering, CSS collection, CSP planning, loops, and visual component ref handling. · `src/core/publisher/index.ts`
- [Persistence contracts](https://github.com/corebunch/instatic/blob/main/src/core/persistence/index.ts): typebox contracts · Shared CMS/auth/data/media/publish/runtime schemas and validation helpers used by server and clients. · `src/core/persistence/index.ts`
- [Plugin SDK](https://github.com/corebunch/instatic/blob/main/src/core/plugin-sdk/index.ts): plugin contracts · Builders, manifest types, permissions, admin/page/panel/resource schemas, and sandbox interfaces. · `src/core/plugin-sdk/index.ts`
- [Site import](https://github.com/corebunch/instatic/blob/main/src/core/siteImport/index.ts): ingest pipeline · HTML/CSS/font/media ingestion, plan building, rewrites, and commit logic for importing sites. · `src/core/siteImport/index.ts`
- [Site runtime](https://github.com/corebunch/instatic/blob/main/src/core/site-runtime/index.ts): runtime contracts · Runtime config, asset manifest, and import-analysis contracts for the public site runtime. · `src/core/site-runtime/index.ts`

### Admin

React/Vite editor and workspaces for site, content, data, media, plugins, users, dashboard, and AI.

- [Admin router](https://github.com/corebunch/instatic/blob/main/src/admin/router.tsx): spa routing · Vite/React app shell, routing, auth gates, and workspace navigation. · `src/admin/router.tsx`
- [Site editor](https://github.com/corebunch/instatic/blob/main/src/admin/pages/site/SitePage.tsx): canvas workspace · Canvas-driven editor for pages, layouts, templates, and visual components with its own store and panels. · `src/admin/pages/site/SitePage.tsx`
- [Content workspace](https://github.com/corebunch/instatic/blob/main/src/admin/pages/content/ContentPage.tsx): editor workspace · Content collection and document editor with live canvas, agent bridge, and collection tools. · `src/admin/pages/content/ContentPage.tsx`
- [Data workspace](https://github.com/corebunch/instatic/blob/main/src/admin/pages/data/DataPage.tsx): table workspace · Data-table management UI for schemas, rows, relations, previews, and exports. · `src/admin/pages/data/DataPage.tsx`
- [Media workspace](https://github.com/corebunch/instatic/blob/main/src/admin/pages/media/MediaPage.tsx): asset workspace · Media library, folders, upload queue, variants, viewers, and replacement flows. · `src/admin/pages/media/MediaPage.tsx`
- [Plugins page](https://github.com/corebunch/instatic/blob/main/src/admin/pages/plugins/PluginsPage.tsx): plugin admin · Installed plugin management, permissions review, schedules, settings, and embedded plugin UI. · `src/admin/pages/plugins/PluginsPage.tsx`

### Shared UI

Reusable UI primitives and built-in editor modules shared across admin and runtime.

- [UI kit](https://github.com/corebunch/instatic/tree/main/src/ui/components): primitives · Reusable buttons, dialogs, tables, inputs, widgets, and other shared UI primitives. · `src/ui/components`
- [Base modules](https://github.com/corebunch/instatic/tree/main/src/modules/base): editor blocks · Composable editor blocks such as text, button, image, link, container, forms, list, outlet, and visual component refs. · `src/modules/base`

### Public runtime

Generated public-site artifacts and the minimal serving/runtime path.

- [Static artifacts](https://github.com/corebunch/instatic/blob/main/server/publish/staticArtefact.ts): generated output · Published HTML, CSS, scripts, and asset bundles served to public visitors. · `server/publish/staticArtefact.ts`

## Connections

- Server entry → Router: boots · The server entry initializes and hands requests to the router.
- Router → CMS handlers: dispatches · Router sends authenticated admin/API requests to CMS handlers.
- Router → Public router: serves · Router exposes the public-site serving path.
- Router → Auth: gates · Authentication and step-up policies protect admin routes.
- CMS handlers → Repositories: uses · Feature handlers persist through repository modules.
- Repositories → DB layer: queries · Repositories isolate SQL and dialect details behind the DB layer.
- CMS handlers → Persistence contracts: validates · Handlers rely on shared persistence schemas and validation helpers.
- CMS handlers → Core domain: depends on · Backend logic uses canonical domain models instead of duplicating rules.
- Publisher → Core publisher: renders with · Server publish uses shared rendering and CSS logic.
- Publisher → Repositories: reads · Publishing loads site state, rows, media, and publish records from repositories.
- Publisher → Static artifacts: writes · Publisher emits static artefacts and updated bundles.
- Public router → Static artifacts: serves · Public routing prefers prebuilt artefacts before dynamic fallback.
- Public router → Publisher: falls back to · Dynamic requests can trigger live rendering behavior from the publisher stack.
- Plugin host → Plugin SDK: implements · Plugin host/runtime follows the shared SDK contracts.
- Plugin host → Repositories: stores · Plugin state, secrets, schedules, and records persist via repositories.
- AI runtime → Core domain: uses · AI tools operate on shared content/site schemas and snapshots.
- Admin router → Site editor: routes to · The admin shell routes into the site editor workspace.
- Admin router → Content workspace: routes to · The admin shell routes into content editing.
- Admin router → Data workspace: routes to · The admin shell routes into data management.
- Admin router → Media workspace: routes to · The admin shell routes into media management.
- Admin router → Plugins page: routes to · The admin shell routes into plugin administration.
- Site editor → Core domain: models · The site editor store and panels are driven by core domain types.
- Site editor → Base modules: renders · The canvas editor composes built-in modules.
- Content workspace → Core domain: models · Content workspace uses shared content/data schemas.
- Data workspace → Core domain: models · Data workspace uses shared row and table schemas.
- Media workspace → Core domain: models · Media workspace uses shared media/file contracts.
- Plugins page → Plugin SDK: configures · Plugin admin views are shaped by the plugin SDK and manifest contracts.
- Site editor → UI kit: uses · Editor UI relies on shared primitives and chrome components.
- Content workspace → UI kit: uses · Content workspace uses shared UI primitives.
- Data workspace → UI kit: uses · Data workspace uses shared UI primitives.
- Media workspace → UI kit: uses · Media workspace uses shared UI primitives.
- Plugins page → UI kit: uses · Plugin admin UI uses shared UI primitives.
- Page tree → Core domain: defines · Page-tree structures are part of the canonical domain layer.
- Core publisher → Page tree: renders · Rendering walks the page tree and related selector/mutation state.
- Site import → Core domain: ingests into · Import planning produces canonical site and content structures.
- Site runtime → Core publisher: feeds · Runtime contracts support publication and public rendering.
- Base modules → Core domain: registers · Built-in modules define canonical block behavior and schemas through core.