MontRS: The Deterministic 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 safety of Rust's type system.

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(Schema)] 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(Schema, Serialize, Deserialize)]
struct Greeting {
    #[schema(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 }
}

---

👥 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.
• Metadata Markers: Look for @agent-tool and AgentError implementations in the source.

---

🛠 Project Structure

Package	Purpose
core	The architectural engine (Plates, Routing, AppSpec).
cli	Orchestration, scaffolding, and build tools.
agent	Agent-first logic, snapshotting, and error tracking.
orm	SQL-centric database abstraction.
schema	Compile-time validation and data modeling.
test	Deterministic test runtime and E2E tools.

---

License

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