corebunch/instatic

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.