f6fac6c4bc
Fix bin/publish: use correct .env path for rspade_system Fix bin/publish script: prevent grep exit code 1 from terminating script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
282 lines
10 KiB
Plaintext
Executable File
282 lines
10 KiB
Plaintext
Executable File
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
|
|
- Use static on_jqhtml_ready() to wait for JQHTML components to load
|
|
- No manual registration required
|
|
|
|
Lifecycle timing:
|
|
- on_app_ready(): Runs when page initializes, before JQHTML components finish
|
|
- on_jqhtml_ready(): Runs after all JQHTML components loaded and rendered
|
|
|
|
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 |