🦀 Rullst Framework — Official Showcase & Blueprints

The Sovereign SaaS, Full-Stack & Edge/IoT Showcase built with Rullst.

---

🌟 Overview

AI chat rendering and authenticated Nexus/Studio assistants are documented in AI panels. Framework findings are tracked in rullst-errors.md. The Capital/SaaS payment audit and required framework updates are tracked separately in saas-improvements-needed.md. Every deployable example is also governed by the engineering global privacy baseline.

Welcome to the official showcase and blueprints repository for the Rullst Framework (12.0.0). This repository demonstrates how to architect, build, and deploy production-grade, sovereign web applications in pure Rust without JavaScript framework lock-in.

This monorepository contains four live cloud applications, with the SaaS blueprint deliberately split into staging and production deployments:

1. 🌐 Rullst Showcase App: Demonstrates the 5 Frontend Paradigms, Active Record ORM, WAF security layers, Prompt Injection Shield, and Omni cross-platform capabilities.
2. 🎓 Rullst Academy (LMS Blueprint): A full-featured, real-world educational platform with 13 SQLite migrations, course catalog, Argon2 authentication, monotonic lesson progress tracking, quizzes, certifications, and integrated Nexus Admin CMS + Studio Dev Cockpit.
3. 💼 Rullst Portfolio Blueprint: An ultra-fast, modern developer portfolio featuring dark glassmorphic UI, HTMX SSR, project showcase, experience timeline, skills matrix, and Nexus Admin CMS.
4. Rullst SaaS Blueprint: An audited one-time Stripe checkout with separate sandbox and live databases, provider objects, secrets, entitlements, downloadable artifacts, certificates, transactional email, refunds and reconciliation.

---

☁️ Live Cloud Deployments (Azure Container Apps)

All applications run in Microsoft Azure Container Apps on the Azure for Students plan using the Serverless Consumption Tier (Scale-to-Zero):

Note

Cold-start behavior: these demos can scale to zero after being idle. The first visit then has to wake a new Azure replica, so the page may load slowly or briefly appear unavailable. Wait a few seconds and reload once. Persistent failures should be checked in Azure revision and container logs. Keeping minReplicas = 1 avoids scale-to-zero wakeups at the cost of idle usage. See the Azure Container Apps deployment guide.

Application	Live Public URL	Key Features	Admin / Cockpit
🌐 Rullst Showcase	showcase.rullst.win	5 Web Paradigms, WAF Defense, LiveView, Active Record, Groq AI Copilot	🛡️ Nexus Admin: /nexus 🚀 Studio: /studio Public demo login: rullst_demo Password: RullstDemoAccess2026! 🤖 Groq AI: GPT-OSS 120B & Prompt Shield 📖 Showcase Guide
🎓 LMS Academy	lms.rullst.win	Courses, Real Argon2 Auth, Lesson Player, Quizzes, Certificates	🛡️ Nexus Admin: /nexus 🚀 Studio: /studio (Protected by HTTP Basic Auth configured via container environment variables)
💼 Portfolio	portfolio.rullst.win	Dark Glassmorphic UI, HTMX SSR, Project Showcase, Experience Timeline	🛡️ Nexus Admin: /nexus 🚀 Studio: /studio Public demo login: rullst_demo Password: RullstDemoAccess2026! 📖 Portfolio Guide
SaaS Staging	saas-staging.rullst.win	Permanent pre-release Stripe sandbox for checkout, webhook, artifact, email and refund validation; no real charge	Private Nexus credentials; no production Studio process
SaaS Production	saas.rullst.win	Real one-time Stripe checkout, private guide, unlimited Founding Customer certificates, purchase email, refunds and reconciliation	Private Nexus credentials; no production Studio process

---

🏛️ The 5 Web Paradigms in One Binary (Blog Showcase Only / Roadmap v13)

Warning

Important Scope & Architecture Disclaimer (Roadmap Rullst v13.0):
This section and the "5 Web Paradigms in One Binary" demonstration exist exclusively as an exploratory architectural preview inside the Blog Showcase example (rullst-showcase / examples/blog).
This multi-paradigm unification does NOT yet exist natively or completely within the core Rullst framework. It is an experimental proof-of-concept targeted for potential inclusion in the Rullst v13.0 Roadmap.
In Rullst v12.0, the framework focuses strictly on Sovereign Zero-Bundle SSR (html! macro + HTMX), Active Record ORM, RASP/WAF defense layers, and the Nexus Admin CMS.

Paradigm	Route	Technology	Footprint	Ideal For
⚡ Zero-Bundle SSR	/	Declarative HTML5 + html! macro + HTMX	0 KB JS	High-speed SEO pages, CRUD apps, Sub-millisecond TTFB
🔴 LiveView UI	/interactive-counter	Server-driven UI over Tokio WebSockets	0 Client JS	Real-time dashboards, live chats, collaborative tools
🏝️ Reactive Islands	/omni-demo	WebAssembly micro-frontends	Isolated WASM	Complex charts, offline calculators, rich markdown
🎨 Classless CSS	/pico-demo	Pure semantic HTML with Pico.css v2 engine	0 JS / 0 NPM	Clean developer tooling, accessible responsive UIs
📄 Classic Layouts	/templates-demo	File-based Jinja2 / Tera templates	Decoupled HTML	Designers migrating from Laravel, Rails, or Loco.rs

---

🎓 The LMS Academy Blueprint (blueprints/lms)

Tip

Live Interactive Showcase (Open Sandbox):
This deployment is an active demonstration of the production LMS blueprint. It is 100% real and fully functional: visitors are welcome to Sign Up for a test account, Log In with real Argon2id password encryption, explore courses, and track lesson progress.

The LMS Blueprint is a full production-grade application generated via cargo rullst new --blueprint lms:

• Active Record Architecture: 22 domain models covering categories, courses, modules, lessons, quizzes, assignments, rubrics, achievements, and certifications.
• Durable Migrations: 13 sequential SQLite migrations applied automatically on container boot.
• Identity & Security: Full Argon2id password hashing, encrypted cookie sessions (SameSite=Lax, Secure), double-submit CSRF protection, and WAF defense.
• Student Experience: Public course search with category filtering, lesson player with captions, monotonic progress tracking (no regressions), and dynamic certificate verification.
• Control Centers:
  • 🛡️ Nexus Admin Panel (/nexus): Auto-generated admin CRUD for all 22 models.
  • 🚀 Studio Cockpit (/studio): Live telemetry, query profiler, and security radar.
  • Access Security: Protected by HTTP Basic Auth configured via NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD environment variables.
• Pre-Flight Verification: See the official LMS Audit Protocol and LMS Audit Report.

---

💳 The SaaS Payment Blueprint (blueprints/saas)

The audited SaaS example is published in two deliberately isolated environments: permanent Stripe sandbox and customer-facing production. Rullst Capital 12.0.0 exports 10 incoming billing adapters and 1 outgoing payout adapter, but adapter presence is not the same as a usable live checkout. This example currently enables only an application-owned Stripe one-time path after a server-side Price check; Razorpay and the other providers remain report/roadmap entries until each has an audited one-time contract. Known Capital defects and v12 capability boundaries are shown directly in its UI.

Payments remain disabled by default in source. Staging uses Stripe test data; production uses separate live credentials and can create a real charge. The two deployments also use separate persistent PostgreSQL databases, webhook secrets, Price IDs, application keys and private administration credentials. No private credential is included in this repository. Staging remains the permanent release gate: every checkout, webhook, download, certificate, email and refund change is validated there before the exact commit is promoted to production.

The sandbox flow grants a downloadable test report and a clearly test-only Rullst Sandbox Pioneer certificate. Every reconciled production purchase grants the private Stripe implementation guide and a Rullst Founding Customer certificate; the certificate has no quantity limit. A persistent transactional outbox sends the buyer authenticated guide, certificate and dashboard links, plus public Rullst, source repository and Discord community links, without marketing tracking. Refunds and disputes revoke the corresponding access after provider confirmation.

See the SaaS blueprint guide for setup and the framework improvement report for the full provider-by-provider and Rullst Mail account-lifecycle audit.

---

📱 Rullst Omni: Multi-Platform Distribution & Instant PWA

"One Rust Codebase. Every Platform."
Rullst eliminates the cost and friction of frontend rewrites. With Rullst Omni (cargo rullst make:omni), your responsive server-rendered application is automatically packaged into lightweight, native desktop and mobile executables without delegating business logic or cryptographic trust to untrusted client code.

graph TD
    RustServer["🦀 Rullst Core Server (Rust / Azure Container)"]
    Web["🌐 Responsive Zero-Bundle Web"]
    PWA["⚡ Instant PWA (Service Worker / Manifest)"]
    Desktop["🖥️ Omni Desktop (Tauri 2.0 / WebView2 / WebKit)"]
    Mobile["📱 Omni Mobile (Android APK & iOS Xcode)"]

    RustServer --> Web
    Web --> PWA
    RustServer --> Desktop
    RustServer --> Mobile

    Desktop --> Win["🪟 Windows (.exe / .msi)"]
    Desktop --> Mac["🍏 macOS (.dmg)"]
    Desktop --> Linux["🐧 Linux (.AppImage / .deb)"]

    Mobile --> Android["🤖 Android (.apk)"]
    Mobile --> iOS["🍏 iOS (.zip Xcode Project)"]

Loading

1. ⚡ Instant Progressive Web App (Zero-Download)

• Install in 1 Second: Direct home screen / desktop shortcut installation via Brave, Chrome, Edge, and Safari (iOS & macOS).
• Zero App Store Fees: No 30% revenue tax, zero developer program delays ($0 vs $99/year).
• Background Offline Sync: Service Worker caches shell UI and media metadata for instant offline boot.
• Interactive Guide: Visit the live /apps page and click "📖 Browser Guide" to view step-by-step installation instructions for your specific browser.

2. 🖥️ Standalone Native Desktop Binaries (~5 MB Footprint)

• Uses the native OS webview (WebView2 on Windows, WebKit on macOS and Linux) instead of bundling a 150 MB+ Chromium/Electron runtime.
• Strict Content Security Policy (CSP) and cryptographic navigation origin pinning.

3. 📱 Native Mobile Packages (Android & iOS)

• Android: Compiles directly to installable Rullst.LMS_1.0.0.apk using the Android SDK/NDK toolchain.
• iOS: Generates a complete native Apple Xcode project (Rullst.LMS_1.0.0_iOS_Xcode.zip) with Swift integration, ready to open in Xcode, run on iPhone/iPad via USB, or submit to the App Store.

📥 Official Release Downloads (v1.0.0)

All native binaries and packages are automatically built, tested, and published to GitHub Releases:

Platform	Package Format	Direct Download	Notes
🪟 Windows	Portable .exe	Download Windows Setup	Standard Windows NSIS installer
🪟 Windows	Enterprise .msi	Download Windows MSI	MSI package for enterprise deployment
🍏 macOS	Universal .dmg	Download macOS DMG	Apple Silicon (M1/M2/M3/M4) & Intel
🐧 Linux	Portable .AppImage	Download Linux AppImage	Runs on Ubuntu, Fedora, Arch, Debian
🐧 Linux	Debian .deb	Download Debian/Ubuntu Package	dpkg -i / apt install ready
🤖 Android	Mobile .apk	Download Android APK	Direct install on Android phones/tablets
🍏 iOS	Xcode Project .zip	Download iOS Xcode Project	Unzip and open in Xcode on macOS

🛠️ Developer CLI Commands (cargo rullst make:omni)

To scaffold native Omni wrappers for any Rullst project:

# 1. Scaffold desktop shell:
cargo rullst make:omni --platform desktop

# 2. Scaffold mobile support with backend pinning:
cargo rullst make:omni --platform android,ios \
  --backend-url https://rullst-lms.redpond-24d9228d.eastus.azurecontainerapps.io \
  --identifier dev.rullst.lms \
  --product-name "Rullst LMS"

# 3. Test locally:
cargo rullst omni desktop   # Runs native desktop window
cargo rullst omni android   # Boots Android emulator with ADB reverse tunnel
cargo rullst omni ios       # Opens in iOS Simulator via Xcode

---

📦 Blueprints Catalog (cargo-rullst)

This showcase serves as the companion guide to the official scaffolds generated by the cargo-rullst CLI tool (v12.0.0):

# 1. Install the official CLI
cargo install cargo-rullst --version 12.0.0

# 2. Scaffold official blueprints:
cargo rullst new my-saas      --blueprint saas       # SaaS auth, billing models and Capital adapters; audit live operations before use
cargo rullst new my-erp       --blueprint erp        # Double-entry Accounting, Inventory, Ledger, and RBAC
cargo rullst new my-lms       --blueprint lms        # Courses, Lessons, Quizzes, and Certifications
cargo rullst new my-portfolio --blueprint portfolio  # Ultra-fast developer showcase with dark glassmorphic UI
cargo rullst new my-app       --blueprint blank      # Minimal, pure high-performance skeleton

---

🚀 Running Locally

Prerequisites

• Rust 1.96+ (Rust 2024 Edition)
• SQLite 3

Quickstart (Showcase App)

# 1. Clone this repository
git clone https://github.com/Rullst/examples.git
cd examples

# 2. Copy environment template
cp .env.example .env

# 3. Run the showcase server
cargo run

Access the local showcase endpoints:

• 🌐 Web Showcase: http://127.0.0.1:3000
• 🛠️ Rullst Studio (Dev Cockpit): http://127.0.0.1:5555
• 🛡️ Nexus Admin CMS: http://127.0.0.1:3000/nexus

Running the LMS Blueprint Locally

cd blueprints/lms
cargo run
# Open http://127.0.0.1:3000 (LMS Catalog, Login, Registration, Nexus, and Studio)

Running the Portfolio Blueprint Locally

cd blueprints/portfolio
cargo run
# Open http://127.0.0.1:3000 (Dark Glassmorphism Portfolio & Nexus CMS at /nexus)

Running the Audited SaaS Blueprint Locally

cd blueprints/saas
cp .env.example .env
cargo rullst db:migrate
cargo run
# Open http://127.0.0.1:3000; payment checkout remains disabled by default.

Read the payment setup and safety checklist before adding any provider secret. Use provider test data before considering a live charge.

---

🐳 Container Architecture: Podman + Caddy + cargo-chef

This repository includes a production-grade Containerfile designed for memory-constrained environments (such as Azure for Students B1s instances with 1 GB RAM).

⚡ Blazing-Fast Caching with cargo-chef

Unlike standard container builds that take 10–15 minutes to recompile all dependencies on every code change, our build uses cargo-chef:

1. Planner: Generates recipe.json with dependency tree.
2. Cooker: Pre-compiles all external crates and caches the layer.
3. Builder: Compiles only your application code (< 30 seconds).

🏃 Running with Podman / Docker Compose

# Set your domain or public IP in .env
echo "DOMAIN=blog.yourdomain.com" >> .env

# Start Rullst + Caddy with automatic HTTPS
podman-compose up -d --build
# or
docker compose up -d --build

---

☁️ Azure for Students Free Deployment Guide

This project is optimized for the Azure for Students free tier (750 hours/month of Linux Standard_B1s VM) as well as Azure Container Apps:

1. Azure VM Setup

1. In the Azure Portal, create a Virtual Machine:
   • Size: Standard_B1s (1 vCPU, 1 GiB RAM).
   • OS: Ubuntu 24.04 LTS x64.
   • Inbound Ports: Open 22 (SSH), 80 (HTTP), and 443 (HTTPS).

2. Host Provisioning (One-Liner)

SSH into your Azure VM and run:

# Install Podman and Podman Compose (Daemonless, saves ~150 MB RAM vs Docker)
sudo apt update && sudo apt install -y podman podman-compose git

3. Clone & Launch

git clone https://github.com/Rullst/examples.git /opt/rullst-examples
cd /opt/rullst-examples
cp .env.example .env

# Configure your public IP or domain
nano .env

# Launch application with Caddy SSL auto-issuance
podman-compose up -d

Caddy will automatically obtain a valid Let's Encrypt / ZeroSSL certificate for your domain as soon as the first request arrives.

---

🔒 Security & Repository Lifecycle Note

• No Private Secrets: This repository contains no private credentials, keys or API tokens. The documented Showcase/Portfolio login is intentionally public demo data; every sensitive production credential must still be supplied through .env, a secret store or container configuration.
• Audited Blueprint: The LMS blueprint has passed the formal pre-flight integration audit (Protocol | Report) with a CONDITIONAL GO verdict.

---

📄 License

Distributed under the MIT License. Created with ❤️ by the Rullst Core Team.