rspade_system/app/RSpade/man/rspade.txt

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.
        <User_Profile_Card> instead of <div class="card">

    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:
        Development workflow uses database snapshots:
        - migrate:begin    Creates snapshot before changes
        - migrate          Runs migrations with validation
        - migrate:commit   Commits changes and removes snapshot
        - migrate:rollback Restores snapshot if problems occur

        Production workflow skips snapshots (test thoroughly 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