1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
//! Beginner guides and tutorials for building Lariv applications and plugins.
//!
//! These guides explain concepts step by step with copy-paste examples. They mirror the
//! structure of the API reference on [`crate::app`], [`crate::http`], [`crate::template`],
//! and related modules, but focus on *how to build* rather than *what each type does*.
//!
//! # Start here
//!
//! | Guide | Topic |
//! |-------|-------|
//! | [`quickstart`] | Build a Hello World plugin from scratch |
//! | [`app`] | Plugin entrypoint and `define_plugin_install!` |
//! | [`routes`] | HTTP routing with `define_plugin_routes!` |
//! | [`templates`] | Maud page types and template registration |
//! | [`handlers`] | Axum handlers, auth extractors, HTMX responses |
//! | [`layers`] | View middleware stacks (load, list, create, update, delete) |
//! | [`patch`] | Query and form patchers for list/detail layers |
//! | [`components`] | UI builders (fields, inputs, tables, shells) |
//! | [`config`] | TOML configuration sections |
//! | [`entities`] | SeaORM models and relations |
//! | [`migrations`] | Database schema migrations |
//! | [`commands`] | CLI subcommands |
//!
//! # Project layout
//!
//! A typical Lariv application looks like this:
//!
//! ```text
//! <project root>/
//! ├── Cargo.toml
//! ├── config.toml # database URL, bind address, plugin sections
//! ├── src/
//! │ ├── main.rs # or src/bin/lariv.rs — install plugins, serve
//! │ └── plugins/
//! │ └── hello/
//! │ ├── mod.rs # plugin tag + define_plugin_install!
//! │ ├── routes.rs # define_plugin_routes!
//! │ ├── templates.rs # RenderTemplate pages + define_register_items!
//! │ ├── handlers.rs # async Axum handler fns
//! │ ├── config.rs # optional [hello] TOML section
//! │ ├── entities/ # optional SeaORM models
//! │ ├── migrations/ # optional SeaORM migrators
//! │ └── cli.rs # optional CLI subcommands
//! └── data/ # SQLite file (when using default database_url)
//! ```
//!
//! # Application bootstrap
//!
//! Every binary follows the same lifecycle:
//!
//! ```ignore
//! use lariv_rs::app::App;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//! let app = App::new_web_app();
//! let app = my_plugin::install(app);
//! // … install other plugins …
//! let app = app.load_config("config.toml").await?;
//! let mounted = app.mount();
//! mounted.run().await? // default: serve HTTP
//! }
//! ```
//!
//! CLI subcommands are registered automatically: `migrate`, `seed`, and `serve`.
//!
//! ```text
//! cargo run -- migrate # apply SeaORM migrations
//! cargo run -- seed # run startup seed hooks
//! cargo run -- serve # start the HTTP server (also the default)
//! ```
//!
//! # Plugin file roles
//!
//! | File | Purpose |
//! |------|---------|
//! | `mod.rs` | Plugin tag, `define_plugin_install!`, state hooks |
//! | `routes.rs` | URL paths → handlers via `define_plugin_routes!` |
//! | `templates.rs` | Page structs implementing [`RenderTemplate`](crate::template::RenderTemplate) |
//! | `handlers.rs` | Async functions called by routes; build pages and return HTML |
//! | `config.rs` | Struct + [`ConfigSection`](crate::config::ConfigSection) for TOML |
//! | `entities/` | SeaORM `Model` / `ActiveModel` definitions |
//! | `migrations/` | SeaORM migration modules |
//! | `cli.rs` | Clap subcommands via [`CommandRegistrar`](crate::command::CommandRegistrar) |
//! | `apps.rs` | Dashboard tile via [`define_register_apps!`](crate::apps::define_register_apps) |
//!
//! See individual guides for worked examples of each file.