NAME rspade - Rapid Single Page Application Development Environment SYNOPSIS Modern PHP/Laravel framework for building B2B SaaS applications with multi-tenant architecture, real-time features, and Visual Basic-inspired rapid development workflow DESCRIPTION RSpade is a complete application framework built on Laravel that provides a structured, opinionated approach to building modern web applications. Think Visual Basic for the web: a complete runtime environment where developers write application code that runs within the framework. Core Philosophy: VB6 apps run in the VB6 runtime on Windows RSX apps run in the RSpade runtime on Laravel RSpade provides the complete runtime environment. Developers write their application in the /rsx/ directory, and the framework handles routing, compilation, asset management, authentication, and deployment. PROJECT GOALS Primary Goal: Starter Template SaaS Application RSpade aims to provide a fully functional, production-ready SaaS application that developers can take and modify into their next project. The framework provides 90% of what most applications need, with code that is simple, flexible, and easy to customize. The reference application in /rsx/ is not just test code - it's a complete working example that demonstrates best practices and provides the foundation for real applications. Design Principles: - One Size Fits Most: Works for 90% of use cases out of the box - Simple and Flexible: Easy to understand and modify - MVP-Focused: Just enough engineering, no over-engineering - Developer-First: Built for developers to extend and customize - Convention Over Configuration: Sensible defaults, minimal setup What RSpade Provides: - Multi-tenant architecture (works for single-site too) - Complete authentication system (Slack-style invitations) - User management and role-based access - File upload and attachment system - Real-time features (planned) - Full-text search (planned) - Email system (planned) - Professional UI components (jqhtml) - Automatic asset compilation - Type-safe routing - Model-based API endpoints What Developers Customize: - Business logic and domain models - UI/UX specific to their application - Custom workflows and processes - Integration with third-party services - Branding and theming ARCHITECTURE Two-Part System: /system/ Framework runtime (RSpade core) /rsx/ Application code (your SaaS app) Framework Layer (system/): - Core runtime and bootstrapping - Manifest system (automatic discovery) - Bundle compiler (asset pipeline) - Authentication and session management - Database models and migrations - Developer tooling (artisan commands) - Framework documentation Application Layer (rsx/): - Controllers with #[Route] attributes - Models extending framework base classes - Blade templates with jqhtml components - JavaScript classes (automatic bundling) - SCSS styles (automatic compilation) - Configuration overrides - Application-specific features No PSR-4 Required: Unlike traditional Laravel, RSpade uses manifest-based discovery. Files can be organized however makes sense. The manifest finds everything automatically. No namespace rules to follow. DEVELOPMENT WORKFLOW 1. Developer Clones RSpade - Gets complete working SaaS application - User management, authentication, file uploads already working - Multi-tenant architecture pre-configured - Professional UI with working examples 2. Developer Customizes Application - Remove features they don't need - Add domain-specific models and logic - Customize UI/UX for their use case - Configure settings in /rsx/resource/config/ 3. Framework Handles Everything Else - Automatic route discovery via #[Route] attributes - Automatic asset compilation (JS, SCSS) - Automatic model constant generation - Automatic API endpoint generation - Session management and authentication - Multi-tenant data segregation 4. Deploy to Production - Framework optimizes everything automatically - Manifest caching for performance - Asset minification and versioning - Production-ready out of the box CONFIGURATION PHILOSOPHY Settings as Developer Tools: Configuration settings in RSpade are provided primarily as convenience switches for rapid development. They let developers quickly test different behaviors without modifying code. Example: signup_mode = 'invite_only' vs 'anonymous' However, the framework's philosophy is that developers should ultimately find the code controlling these features and customize it to their exact needs. Configuration switches are training wheels that help you understand the system before diving into the code. When you're ready: 1. Find the code using the config setting 2. Remove the switch 3. Hardcode your desired behavior 4. Customize the implementation to your needs This keeps the codebase simple and prevents the "configuration explosion" problem where every feature has 10 different modes. VISUAL BASIC INSPIRATION RSpade borrows concepts from Visual Basic that made it successful: Complete Development Environment: Like VB provided forms, controls, and runtime, RSpade provides controllers, components, and framework runtime. Everything needed to build an application is included. Form-Based Design: Controllers are like VB forms. Routes are like form events. The framework manages the lifecycle. Property Sheets: Attributes like #[Route] and #[Auth] are like VB property sheets. Declarative configuration attached to methods. Component Model: Jqhtml components are like VB controls. Reusable, composable, with lifecycle methods (on_create, on_load, on_ready). Rapid Development: No complex build systems. Change code, refresh browser, see results. Like VB's immediate mode. MULTI-TENANT BY DEFAULT Every RSpade application is multi-tenant capable out of the box: Single-Site Applications: - Just use site_id = 1 for everything - No special configuration needed - Architecture identical to multi-tenant - Easy upgrade path if needs change Multi-Tenant Applications: - Users can belong to multiple organizations - Each organization (site) has independent data - Slack-style organization picker after login - Site-specific user roles and permissions Future: Subdomain Isolation: - Each tenant gets their own subdomain - acme.yourapp.com, widget.yourapp.com - Traditional "have account or don't" flow - Planned feature, not yet implemented AUTHENTICATION SYSTEM Slack-Style Invitations: - Admins invite users by email - Users create accounts when accepting invites - Email verified via invitation click - One login identity, multiple site memberships Configuration Modes: signup_mode = 'anonymous' Anyone can create account signup_mode = 'invite_only' Only invited users can join signup_mode = 'disabled' No new accounts (closed system) verification_required = 'email', 'sms', 'either', 'both' Flexible Architecture: - Works for single-site or multi-tenant - Works for internal intranet or public SaaS - Developers customize to their needs See: rsx:man auth - Complete authentication documentation JQHTML COMPONENT SYSTEM Modern component system built on jQuery: Semantic-First Design: Name components what they ARE, not how they look. instead of
Lifecycle Methods: on_create() Initialize before render on_load() Load data (async) on_render() Template rendered on_ready() DOM ready, attach events Type-Safe: Components are JavaScript classes Full IDE autocomplete support Compile-time error checking See: rsx:man jqhtml - Complete component documentation MANIFEST SYSTEM Automatic Discovery: The manifest system finds everything automatically: - Controllers and routes - Models and database tables - JavaScript classes - SCSS files - Blade templates - jqhtml components No Configuration Needed: Unlike Laravel where you register providers and routes, RSpade discovers everything. Add a file, the manifest finds it. Development vs Production: Development: Manifest rebuilds on every request (instant changes) Production: Manifest cached (maximum performance) See: rsx:man manifest_api - Complete manifest documentation DATABASE ARCHITECTURE Restrained Column Types: - BIGINT only for integers (INT auto-converts to BIGINT) - TINYINT(1) exclusively for booleans (is_active, is_enabled) - No unsigned integers (signed for easier migrations) - UTF8MB4 for all text columns Required Structure: Every table must have: id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY Timestamp columns automatically added: created_at, updated_at (with proper defaults) Migration Safety: The migrate command handles snapshots automatically: Development mode: - php artisan migrate - Automatically creates snapshot before running - On success: commits and regenerates constants/bundles - On failure: automatically rolls back to snapshot Production mode: - php artisan migrate - Runs directly without snapshot protection - Test thoroughly in development first Site-Based Multi-Tenancy: Models extend one of two base classes: Rsx_Model_Abstract - Global/system-wide data (countries, settings) - No automatic site scoping Rsx_Site_Model_Abstract - Tenant-specific data (users, projects, clients) - Automatic site_id column and index - All queries filtered by current session site_id - Cannot change site_id on existing records - Cannot access cross-site data (fatal error) Single-site applications use site_id = 1 for everything. Easy upgrade path to multi-tenant if needed. Eager Loading Prohibited: RSpade bans eager loading (with(), load()) to prevent recursive loading chains. Use explicit queries instead. Future optimization will use caching strategies rather than eager loading. See: rsx:man model - Complete model system documentation See: rsx:man migrations - Migration system and safety BUNDLE SYSTEM Automatic Asset Compilation: Bundles define dependencies, framework compiles everything: - JavaScript classes → Minified bundle - SCSS files → Minified CSS - npm packages → Vendor bundles - Source maps → Debugging support Simple Configuration: Bundle files list includes, framework handles the rest: - Dependency resolution - Compilation and minification - Cache busting (automatic versioning) - Development vs production optimization See: rsx:man bundle_api - Complete bundle documentation DEVELOPMENT FOCUS Current Phase: Starter Template SaaS The framework core is stable. Current development focus is building out the reference application in /rsx/ as a complete, production-ready SaaS starter template. We're adding backend features as needed: - File attachments (complete) - Authentication (in progress) - Email system (planned) - Full-text search (planned) - Real-time updates (planned) - Payment processing (planned) Framework vs Application: Framework development (system/) focuses on: - Core runtime stability - Build system performance - Developer tooling - Framework documentation Application development (rsx/) focuses on: - Complete working features - Best practice examples - Professional UI/UX - Real-world use cases GETTING STARTED For Framework Developers: Read: /var/www/html/CLAUDE.md Contains: Framework development guidelines Focus: Building the framework runtime itself For Application Developers: Read: /system/docs.dist/CLAUDE.dist.md Contains: Application development guidelines Focus: Building apps using the framework Man Pages: rsx:man auth Authentication system rsx:man jqhtml Component system rsx:man routing Type-safe routing rsx:man model Database models rsx:man manifest_api Discovery system rsx:man bundle_api Asset compilation Example Code: /rsx/ Complete working application Study this code to understand best practices PHILOSOPHY 90% Solution: RSpade aims to provide 90% of what most applications need. The remaining 10% is YOUR domain expertise, YOUR business logic, YOUR unique value proposition. Simple and Flexible: Code should be easy to understand and modify. No magic. No over-abstraction. Clear, straightforward implementations. One Way: There should be one obvious way to do things. Not five ways with different trade-offs. One way that works well. Fail Loud: Errors should be obvious and immediate. No silent failures. No fallback systems that hide problems. Developer First: Built for professional developers who will read the code, understand it, and modify it to their needs. SEE ALSO auth - Authentication and user management jqhtml - Component system routing - Type-safe routing model - Database models manifest_api - Automatic discovery bundle_api - Asset compilation