Expand description
Lariv application kernel — configuration, HTTP server wiring, and aggregated plugin registries.
lariv-rs is a compile-time plugin web application framework built on Axum, SeaORM, Maud, and HTMX 4.
§Architecture
The app lifecycle has three phases:
- Builder —
Appholds an HList of capability stores (hooks + items). Plugins calldefine_plugin_install!to register deferred hooks for routes, templates, migrations, CLI commands, etc. - Mount —
App::mountresolves hooks, folds capabilities toTaggedoutputs, and produces aMountedApp. - Runtime — Axum serves HTTP; handlers extract mounted state via
Cap.
§Quickstart
ⓘ
use lariv_rs::app::App;
use lariv_rs::plugins::{dashboard, users};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let app = App::new_web_app();
let app = users::install(app);
let app = dashboard::install(app);
let app = app.load_config("config.toml").await?;
let mounted = app.mount();
mounted.run_migrations().await?;
mounted.run_seeds().await?;
mounted.run().await
}See app for lifecycle details and plugins for bundled plugins.
§Beginner guides
Step-by-step tutorials for new plugin authors live in the docs module:
docs::quickstart— Hello World plugin tutorialdocs— project layout and guide index
§Core modules
| Module | Role |
|---|---|
app | Builder and mounted app lifecycle |
capability | Capability stores, hooks, mount folding |
tag | Type-level tagging via tag::Tagged |
traits | HList lookup, add, replace, remove |
http | Route registry and Axum router |
template | Maud page template registry |
layers | Compile-time view middleware stacks |
components | Maud UI builders (fields, tables, shells) |
web | HTMX-aware page rendering helpers |
html_form | Form macro and widget traits |
rt | Large-stack process entry helpers (main) |
config | TOML configuration loading |
db | SeaORM connection capability |
migration | Composite SeaORM migrator |
command | CLI command registration |
hooks | State attachment and seed hooks |
apps | Dashboard app tile catalog |
export | XLSX export table catalog |
llm_tools | Gemini function-calling tools |
rune_env | Rune script native bindings |
grapesjs | Website builder block/component registries |
genai | Gemini HTTP client |
views | Named view registry (PWA offline page) |
§Plugin authoring
| Module | Role |
|---|---|
plugin_install | define_plugin_install! macro |
plugin_routes | define_plugin_routes! DSL reference |
define_plugin_routes | Proc-macro re-export |
§Bundled plugins
| Plugin | Module | Purpose |
|---|---|---|
| Users & auth | plugins::users | JWT/scrypt auth, roles, user CRUD |
| Dashboard | plugins::dashboard | Apps launchpad and home redirects |
| Blog | plugins::blog | Articles and hierarchical tags |
| Filesystem | plugins::filesystem | DB-backed virtual filesystem |
| Website | plugins::website | DB routes, Minijinja pages, GrapesJS builder |
| LLM assistant | plugins::llm_assistant | Gemini chat, skills, WebSocket |
| OTP recovery | plugins::otp | SMS/email one-time password recovery |
| PWA | plugins::pwa | Manifest, service worker, offline page |
| Export | plugins::export | XLSX data export UI |
| Signup | plugins::signup | Public self-service signup |
Proc-macro derives expand to ::lariv_rs::… paths; this crate aliases itself as lariv_rs for in-tree use.
Re-exports§
pub use paste;
Modules§
- app
- Application lifecycle: builder phase, mount, and runtime CLI/HTTP.
- apps
- App catalog capability — plugins register launchable tiles; dashboard reads them live.
- capability
- Uniform capability shape: hooks + items, infallible
Capability::mount→Tagged. - command
- CLI command registry capability — plugins register subcommands; clap builds and dispatches them.
- components
- Reusable Maud UI builders — fields, inputs, buttons, layouts, shells, and forms for the Lariv application framework.
- config
- TOML configuration loading and the core
AppConfigsection. - datetime
- Timezone-aware datetime display/edit helpers (stored values remain
DateTime<Utc>). - db
- Shared SeaORM database connection capability.
- docs
- Beginner guides and tutorials for building Lariv applications and plugins.
- duration
- Duration parsing and formatting for storage as nanoseconds (
i64). - export
- Export catalog capability — plugins register exportable DB tables.
- genai
- Shared Gemini HTTP client (used by LLM Assistant, Totschool AI workers, etc.).
- grapesjs
- GrapesJS registries capability — plugins register blocks, components, traits, and themes.
- hooks
- Deferred state-attachment and startup seed hooks.
- html_
form - Attribute-macro-backed HTML forms:
HtmlForm+FormWidget. - http
- Typed HTTP routing capability for Lariv apps.
- layers
- Compile-time view layer stack for request processing and page data assembly.
- llm_
tools - LLM tool registry capability — plugins register tools; assistant chat runs them.
- migration
- Database migration capability — plugins register SeaORM migrators; CLI runs them as one composite
up. - picker
- Type-safe FK / many-to-many picker responses.
- plugin_
install - Declarative plugin
installhelper — expandsAfter*type aliases,InstallOutput, andinstall. - plugin_
routes - Declarative plugin HTTP route registration — proc-macro generated tags and
crate::http::RouteRegistrar. - plugins
- Bundled Lariv plugins for standard web application capabilities.
- rt
- Process / thread runtime helpers for deep HList install/mount chains.
- rune_
env - Rune environment registry — plugins register bindings for assistant scripts.
- tag
- Type-level tagging for HList items and compile-time type equality.
- template
- Compile-time template registry for page types.
- traits
- HList manipulation traits for the capability system.
- views
- Runtime string→handler view registry for dynamic page dispatch.
- web
- HTTP response helpers for HTML pages, cookies, and HTMX-aware rendering.
Macros§
- define_
passthrough_ cap - define_
passthrough_ cap_ impl CapStore<Tag, HNil, Value>that mounts asTagged::new(items).- define_
plugin_ install - Generate the capability-stack
installfunction and intermediate type aliases. - define_
plugin_ routes - Generate route tags, proof type, and
RouteRegistrarhook. - define_
register_ apps - Register a dashboard app tile for a plugin.
- define_
register_ export - Register an exportable table for a plugin.
- define_
register_ items - Declare item tags and a
Register*impl for a marker-style capability. - define_
register_ migrations - Register a plugin migrator via a local hook type.
- define_
replace_ templates - Register a template hook that replaces tagged pages (and optionally prepends new ones).
- impl_
create_ modal - Implement
CreateModalfor a swap key with typed GET/POST routes and form identity. - impl_
picker_ modal - Implement
PickerModalpairing a picker dialog key with its inner table key. - swap_
key - Declare a
SwapKeytype with a literal id.
Attribute Macros§
- main
- Attribute macro: run
async fn mainon a thread with a raised stack size.