Vyasa Modular Architecture
Language
Core: The mandatory runtime layer that owns content mounting, routing, rendering contracts, shared page shell, wikilinks, and RBAC. Avoid: Kernel, base app
Extension: An optional module that adds behavior through core-owned contracts without becoming required by every Vyasa site. Avoid: Plugin, addon
Markdown Pipeline: The core-owned rendering contract that turns Markdown into HTML while allowing extensions to register syntax handlers. Avoid: Renderer plugin system
Extension Configuration:
The .vyasa TOML declarations that enable and configure extension behavior for a site or folder.
Avoid: Entry-point discovery, implicit auto-loading
Root Configuration:
The root .vyasa file that decides which extensions load at server start.
Avoid: Folder configuration
Folder Configuration:
A folder-local .vyasa file that tunes already-loaded behavior for a content subtree.
Avoid: Extension loading configuration
Built-in Extension: An extension shipped with Vyasa and enabled explicitly through extension configuration. Avoid: External package, third-party extension
Override Slot: A named core contract where exactly one extension may replace default behavior. Avoid: Last-writer-wins hook
Theme Extension: An extension that changes visual tokens, CSS, typography, colors, or component styling. Avoid: Custom CSS bundle
Layout Extension: An extension that changes page structure, chrome placement, visible regions, gestures, or navigation affordances. Avoid: Theme
Render Extension: An extension that adds or overrides Markdown rendering behavior through the Markdown Pipeline. Avoid: Markdown plugin
Extension Bundle: A built-in extension folder containing Python code, CSS, JavaScript, and other assets behind one extension id. Avoid: Loose module
Extension App: The restricted registration surface that an extension uses to add routes, assets, markdown handlers, layout hooks, config, and lifecycle hooks. Avoid: Raw FastHTML app
Extension Asset: A CSS, JavaScript, image, or other static file exposed by core from an extension bundle. Avoid: Ad hoc static route
Asset Bundle: An ordered group of extension assets loaded only when a route or rendered document asks for it. Avoid: Global dependency graph
Asset Collector: The per-render context object where extensions record which asset bundles a page needs. Avoid: Global asset flag
Default Preset: The built-in extension set enabled automatically to preserve today’s Vyasa behavior. Avoid: Core
Extension Metadata: The Python-declared capabilities, slots, requirements, scoping, and fallback rules for an extension. Avoid: TOML behavior definition
Capability Name: A stable metadata string that names an extension-provided slot, capability, or asset bundle. Avoid: Hook id
See Vyasa Extension Contract Notes for the current slot:*, cap:*, and bundle:* naming rules.
Storage Namespace: A core-assigned durable filesystem territory where one extension may store local data. Avoid: Global extension database path
Extension Config Model: The Pydantic model an extension owns for validating its root and folder configuration. Avoid: Untyped config dict
Error Page Extension: The built-in extension that renders configurable 4xx and 5xx error pages. Avoid: Custom not-found only