NAME rsx_architecture - RSX application structure and organization SYNOPSIS RSX application structure, module organization, and development patterns DESCRIPTION RSX applications follow a standardized module-based architecture that separates framework code from application code. Understanding this structure is essential for organizing files, creating modules, and understanding the development workflow. RSX DIRECTORY STRUCTURE The /rsx/ directory contains all application code organized by modules: /rsx/ ├── app/ # Application modules │ ├── frontend/ # Public website (route: /) │ │ ├── frontend_controller.php │ │ ├── frontend_bundle.php │ │ ├── frontend_view.blade.php │ │ ├── frontend.scss │ │ ├── frontend.js │ │ └── layout.blade.php │ ├── backend/ # Admin panel (route: /admin) │ │ └── (same structure as frontend) │ ├── dashboard/ # User dashboard (route: /dashboard) │ │ └── (same structure as frontend) │ ├── root/ # Super admin (route: /root) │ │ └── (same structure as frontend) │ ├── login/ # Authentication (routes: /login, /logout) │ │ └── (same structure as frontend) │ ├── api/ # Public API endpoints │ │ └── CLAUDE.md # API documentation │ └── demo/ # Demo/example code ├── lib/ # Shared libraries and utilities ├── models/ # Database models ├── theme/ # Global theme assets │ ├── variables.scss # Global SCSS variables │ ├── components/ # Reusable UI components │ └── layouts/ # Shared layouts (if needed) └── main.php # Application-wide middleware hooks MODULE STRUCTURE CONVENTION Each module is self-contained with its own files: File Naming: - Always lowercase: frontend_controller.php - Underscore separation: user_profile_view.blade.php Class Naming: - Noun_Type format: Frontend_Controller, Backend_Bundle - Matches file name pattern View Identifiers: - Noun_Type format: @rsx_id('Frontend_View') - Used for CSS scoping and identification Bundle Rendering: - Required format: {!! Module_Bundle::render() !!} - Example: {!! Frontend_Bundle::render() !!} API ORGANIZATION Two types of API endpoints: Public APIs (/rsx/app/api/): - External-facing endpoints - Include versioning - Public documentation Internal APIs: - Place in module directories: /rsx/app/frontend/api/ - Or in shared location: /rsx/lib/ - Module-specific functionality MODULE HIERARCHY RSX uses a four-level hierarchy for organizing complex applications: Level 1 - Module: - Top-level application section - Route: /module - Has own layout and styling - Example: frontend, backend, dashboard Level 2 - Submodule: - Sub-section within module with embedded layout - Route: /module/submodule - Extends parent module layout - Example: /backend/users, /dashboard/reports Level 3 - Feature: - Specific functionality page - Route: /module/feature or /module/submodule/feature - Individual page within module/submodule - Example: /backend/create, /dashboard/reports/monthly Level 4 - Subfeature: - Sub-page within feature - Route: /module/feature/subfeature or /module/submodule/feature/subfeature - Detailed or step-based pages - Example: /backend/create/step2, /dashboard/reports/monthly/export MODULE FEATURES Each level creates specific file structures: Index Feature (default): - Route: /module - Files in module root: module_index_controller.php - Default landing page for module Additional Features: - Route: /module/feature - Files in subdirectory: module/feature/module_feature_controller.php - Each feature is self-contained Feature Files: - Controller: handles routing and logic - View: Blade template for HTML - JS Class: client-side behavior - SCSS: styling specific to feature SUBMODULE ORGANIZATION Submodules provide hierarchical organization: Layout Structure: - Submodules have embedded layouts extending parent layouts - Allows consistent styling within module family - Parent module controls overall structure File Placement: - Submodule files in: /rsx/app/module/submodule/ - Features within submodule: /rsx/app/module/submodule/feature/ - Maintains clear separation of concerns MODULE CREATION COMMANDS Generate modules with standardized structure using hierarchy commands: Level 1 - Module Commands: php artisan rsx:app:module:create signup Creates: /rsx/app/signup/ with index feature Route: /signup php artisan rsx:app:module:feature:create signup verify_email Creates: /rsx/app/signup/verify_email/ Route: /signup/verify_email Level 2 - Submodule Commands: php artisan rsx:app:submodule:create backend users Creates: /rsx/app/backend/users/ with embedded layout Route: /backend/users php artisan rsx:app:submodule:feature:create backend users create Creates: /rsx/app/backend/users/create/ Route: /backend/users/create Level 3 - Subfeature Commands: php artisan rsx:app:subfeature:create signup verify_email confirm Creates: /rsx/app/signup/verify_email/confirm/ Route: /signup/verify_email/confirm php artisan rsx:app:submodule:subfeature:create backend users create step2 Creates: /rsx/app/backend/users/create/step2/ Route: /backend/users/create/step2 Component Commands: php artisan rsx:app:component:create --name=my_widget --path=rsx/theme/components Creates reusable jqhtml component in theme directory php artisan rsx:app:component:create --name=user_card --module=dashboard Creates component within specific module php artisan rsx:app:component:create --name=form_field --module=backend --feature=users Creates component within module feature COMMAND NAMING RULES All names must be lowercase with underscores: - Correct: user_profile, email_verify, admin_panel - Incorrect: UserProfile, emailVerify, admin-panel Examples of full hierarchy: Module: ecommerce Submodule: ecommerce/products Feature: ecommerce/products/create Subfeature: ecommerce/products/create/images JAVASCRIPT INTEGRATION JavaScript classes auto-initialize: - Extend appropriate base classes - Use static on_app_ready() method for initialization - No manual registration required Lifecycle timing: - on_app_ready(): Runs when page is ready for initialization - For component readiness: await $(element).component().ready() Important limitation: JavaScript only executes when bundle is rendered in HTML output. Won't work with: - JSON API responses - Raw HTML responses - Views without bundle includes SHARED RESOURCES Theme Directory (/rsx/theme/): - variables.scss: Global SCSS variables and mixins - components/: Reusable jqhtml components - layouts/: Shared layout templates (if needed) Library Directory (/rsx/lib/): - Shared utility classes - Common business logic - Internal API helpers Models Directory (/rsx/models/): - Database model classes - Data validation logic - Model relationships MIDDLEWARE INTEGRATION Application-wide hooks via /rsx/main.php: - Extends Main_Abstract - Provides init(), pre_dispatch(), unhandled_route() methods - Handles cross-cutting concerns DEVELOPMENT WORKFLOW 1. Plan module hierarchy (module > submodule > feature > subfeature) 2. Create structure with appropriate artisan commands 3. Implement controllers with route attributes 4. Create view templates with bundle includes 5. Add JavaScript classes for interactivity 6. Style with SCSS in theme or module files 7. Test with rsx:debug command HIERARCHY PLANNING Choose appropriate level based on complexity: Simple Applications: - Use modules and features only - Example: /login, /dashboard, /profile Complex Applications: - Use full hierarchy for organization - Example: /admin/users/create/permissions Planning Questions: - Does this need its own layout? (Use submodule) - Is this a multi-step process? (Use subfeatures) - Will users bookmark this page? (Consider hierarchy depth) BEST PRACTICES Hierarchy Organization: - Start simple: use modules and features first - Add submodules when you need distinct layouts - Use subfeatures for multi-step processes - Avoid deep nesting (4 levels maximum) Module Organization: - Keep modules focused on single responsibility - Use shared /lib/ for cross-module functionality - Place components in /theme/ if truly reusable File Organization: - Follow naming conventions strictly (lowercase, underscores) - Keep related files together in module directories - Use features for complex modules with multiple pages - Group related submodules under logical modules API Design: - Public APIs in /api/ with versioning - Internal APIs close to consuming code - Document API endpoints in module CLAUDE.md files Layout Strategy: - Module layouts for major sections - Submodule embedded layouts for consistent styling - Share common elements through parent layouts SEE ALSO bundle_api - Bundle system documentation controller - Controller patterns and routing manifest_api - Manifest system reference