بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيم

MontRS: The Most Comprehensive Full-Stack Rust Framework

MontRS is a Rust-native, trait-driven framework for building cross-platform applications. It provides a unified, deterministic environment for web, desktop, and mobile, powered by the performance of Leptos and the type safety of Rust.

Philosophy

MontRS exists because building complex applications requires more than just a UI library. It requires a predictable architecture.

• Determinism: The same input should always produce the same output, whether in production or testing.
• Trait-Driven Boundaries: Features are encapsulated in Plates with explicit interfaces.
• Agent-first: Built-in metadata and structured snapshots make MontRS applications natively understandable by agents.

---

🎯 The Golden Path

The "Golden Path" is the recommended workflow for building robust MontRS applications:

1. Scaffold: Start with montrs new <app-name> to get a pre-configured workspace.
2. Define: Use #[derive(Validator)] to define your data models and validation rules.
3. Implement: Build features as Plates. Define unified Routes that bundle your Loader, Action, and View.
4. Verify: Use the TestRuntime for in-process, deterministic testing of your entire application spec.
5. Ship: Deploy to your target (Web, Server, or Desktop) using montrs build.

---

🧠 How to Think in MontRS

• Everything is a Trait: If you want to change behavior (ORM, Auth, Rendering), you implement a trait.
• Unified Routes: A single struct defines the path, parameters, data fetching, and visual representation for a URL.
• The AppSpec is Truth: Your entire application is defined by a serializable AppSpec, making it portable and inspectable.
• No Magic: We prefer explicit registration over reflection or global state.

---

🚀 Minimal Example

use montrs::prelude::*;

#[derive(Validator, Serialize, Deserialize)]
struct Greeting {
    #[validator(min_len = 3)]
    name: String,
}

struct HelloPlate;

impl Plate<AppConfig> for HelloPlate {
    fn register_routes(&self, router: &mut Router<AppConfig>) {
        router.register(HelloRoute);
    }
}

struct HelloRoute;

impl Route<AppConfig> for HelloRoute {
    type Params = EmptyParams;
    type Loader = HelloLoader;
    type Action = EmptyAction;
    type View = HelloView;

    fn path() -> &'static str { "/hello" }
    fn loader(&self) -> Self::Loader { HelloLoader }
    fn action(&self) -> Self::Action { EmptyAction }
    fn view(&self) -> Self::View { HelloView }
}

---

📦 Installing from Source (Local Development)

Since MontRS is not yet published on crates.io, you'll need to build and install from source for local development.

Prerequisites

• Rust toolchain: Install via rustup. MontRS pins a specific nightly version in rust-toolchain.toml — it will be installed automatically on first build.
• WASM target: Required for web builds.

  rustup target add wasm32-unknown-unknown

1. Clone the Repository

git clone https://github.com/afsall-inc/montrs.git
cd montrs

2. Build the CLI

cargo build --package montrs-cli

The binary will be at target/debug/montrs (or target/debug/montrs.exe on Windows).

3. Install the CLI (Optional)

To make montrs available globally:

cargo install --path packages/cli

Alternatively, use cargo run from the project root:

cargo run --package montrs-cli -- <subcommand>

4. Verify

cargo run --package montrs-cli -- --help

Development Workflow

Use the montrs CLI for common development tasks:

montrs fmt          # format all Rust and view! code
montrs test         # run all tests
montrs bench        # run performance benchmarks
montrs serve        # start the dev server with hot-reload
montrs build        # build for production
montrs watch        # watch for changes and rebuild automatically
montrs agent check  # run agent-level diagnostics
montrs agent doctor # full health check

For linting, use cargo clippy directly:

cargo clippy --workspace -- -D warnings

Note for Framework Contributors: If you're working on MontRS itself, run montrs agent doctor after building to verify the environment is healthy.

---

👥 Documentation for Every Audience

1. Application Developers

People building apps with MontRS.

• First 30 Minutes: Start here! Your first onboarding experience.

• Introduction: Your first 10 minutes.

• The Golden Path: How to build the right way.

• Common Mistakes: Avoid frequent pitfalls and architectural anti-patterns.

  2. Framework Contributors

People working on MontRS itself.

• Architecture Overview: How the engine works.
• Package Boundaries: Responsibility of each crate.
• Invariants & Philosophy: The rules we don't break.

3. Agents

Machine-readable context for models.

• Agent-first design: Principles of machine-readability.
• Agent Usage Guide: How to use agent.json and tools.json.
• Spec Snapshot: Understanding the machine-readable project state.
• Skills System: Composable, reusable agent capabilities with multi-step workflows.
• PRDoc: Structured PR documentation for agent review.
• Metadata Markers: Look for @agent-tool, @agent-skill, and AgentError implementations in the source.

---

🛠 Project Structure

Package	Purpose
agent	Agent-first logic, snapshotting, and error tracking.
agentignore	Agent-first file ignore patterns with IDE-specific export.
auth	Plugin-based authentication (email/password, OAuth, 2FA, orgs, API keys).
bench	Statistical benchmarking.
build	Build pipeline facade (re-exports build-core, build-watch, build-serve).
build-core	Build pipeline trait and configuration.
build-serve	Dev server (static file serving via axum).
build-watch	File system watcher with debounced rebuild triggers.
cli	Orchestration, scaffolding, and build tools.
core	The architectural engine (Plates, Routing, AppSpec).
deps	Dependency freshness checking.
desktop	Native desktop (wry webview, winit+wgpu window).
env	Environment variable parsing + .env loading + Tera templates.
fmt	Custom formatter for Rust + view! macros.
haptics	Cross-platform haptic feedback for web, desktop, and mobile.
i18n	Internationalization (macros, plurals, formatting, scoping).
icons	1600+ Lucide icons as Leptos components.
lockfile	Deterministic tool version locking.
log	Structured log store with retention, streaming, and archiving.
metadata	montrs.toml single source of truth (all sections incl. services/proxy).
mobile	Mobile platform adapter (Android/iOS shells).
montrs	Facade crate — re-exports. Minimal logic.
motion	Spring, tween, keyframes, gestures, SVG/CSS animation.
orm	SQL-centric database abstraction.
platform	Platform abstraction (Target enum, PlatformAdapter trait).
plugin	Tool plugin system (asdf/vfox-compatible).
prdoc	Structured PR documentation, auto-generation, changelog.
proxy	Reverse proxy routing <slug>.localhost to service ports.
registry	Tool registry (baked + floating).
renderer	Renderer trait + geometry primitives (wgpu/tiny-skia backends).
runner	Custom task runner config.
runtime	Native Rust runtime (ops, extensions, workers, permissions, GC-free memory).
services	Service supervisor — daemon lifecycle, ready checks, retries, hooks.
shell	Shell integration (bash/zsh/fish/pwsh) + shims.
sigstore	GitHub attestation, cosign, SLSA verification.
test	Deterministic test runtime and E2E tools.
tool	Tool version manager (5 backends: core, cargo, github, http, ubi).
ui	shadcn-inspired component library (91 components) + theme system.
utils	Generic pure functions.
validator	Compile-time validation and data modeling.
web	Web platform adapter (WASM browser bindings).

---

License

MontRS is dual-licensed under Apache-2.0 and MIT.