Vyasa Modular Architecture
- The Core loads zero or more Extensions.
- An Extension depends on Core contracts, but Core must not depend on a specific Extension.
- The Core owns the Markdown Pipeline.
- An Extension may add syntax to the Markdown Pipeline.
- Extension Configuration is the canonical source for enabling extension behavior.
- Initial Extension Configuration targets Built-in Extensions only.
- Built-in Extensions live in the Vyasa repo and can be switched off.
- A disabled Built-in Extension is not loaded at server start.
- Existing sites keep today’s behavior by default.
- Root Configuration controls extension loading.
- Folder Configuration may configure or disable already-loaded extension behavior for its subtree.
- Folder Configuration cannot disable core RBAC.
- Folder-level disabling is available only when an Extension declares that scoped disabling is supported.
- An Extension Bundle is the preferred implementation shape for built-in extensions.
- An Extension registers through an Extension App, not the raw FastHTML app.
- Extension Assets are served from core-managed URLs.
- Asset Bundles are loaded dynamically by page need, not globally by extension presence.
- A render extension uses the Asset Collector to request an Asset Bundle during page rendering.
- Each Extension owns one
[extensions.<id>] TOML namespace.
- Folder Configuration uses the same extension namespace for scoped settings.
- Existing top-level config keys remain supported through compatibility mapping.
- Default Preset includes default layout, default theme, search, error pages, blog home behavior, tabs, diagrams, tasks, slides, and filesystem content.
- Vyasa boot fails when no layout extension is active.
- Theme is required at runtime, but a broken configured theme falls back to the default theme.
- Broken not-found behavior falls back to the default not-found extension.
- Broken search disables search cleanly.
- Broken home behavior falls back to a plain index.
.vyasa selects and configures extensions; Extension Metadata defines extension behavior rules.
- Capability Names let Vyasa validate extension conflicts, dependencies, and load order.
- Storage Namespaces prevent local extension data from colliding and make backup, cleanup, and migration discoverable.
- Extensions depend on capability names for required behavior.
- Extension ids are used only for optional integrations or configuration.
- Each extension owns an Extension Config Model.
- Core merges and validates extension config before passing it to extension code.
- Normal users see concise scoped errors; admins may see detailed diagnostics.
- Error Page Extension owns default configurable 4xx and 5xx pages.
- Extensions are instantiated once during server startup.
- Extensions receive per-request or per-render context instead of storing user state.
- Default extensions are subclassable where stable customization seams exist.
- Simple extensions should not require inheritance.
- Runtime load resolves enabled extensions, validates metadata, registers through the extension app, then applies folder configuration per request.
- Config order does not decide override slot behavior.
- Config order may matter only for explicitly ordered additive extension lists.
- Route extensions declare route prefixes so startup validation can catch route conflicts.
- An Override Slot has at most one active extension.
- A site has at most one active Theme Extension.
- A site has at most one active Layout Extension.
- A Theme Extension changes presentation styling; a Layout Extension changes page structure and interaction surfaces.
- Many Render Extensions may be active together.
- A Markdown syntax marker has exactly one owning Render Extension.