MODULE_ORGANIZATION(3) RSX Framework Manual MODULE_ORGANIZATION(3) NAME Module Organization - RSX application structure and nomenclature SYNOPSIS php artisan rsx:app:module:create php artisan rsx:app:module:feature:create php artisan rsx:app:submodule:create php artisan rsx:app:submodule:feature:create php artisan rsx:app:submodule:subfeature:create DESCRIPTION RSX applications organize code into a hierarchical structure: Module > Submodule > Feature > Subfeature This structure enforces clear separation of concerns and predictable file organization for both developers and AI assistants. NOMENCLATURE Module Top-level section with shared layout and common UI elements. Examples: frontend, admin, api Rule: If pages share a layout, they belong in the same module. Created with: rsx:app:module:create Structure: rsx/app/frontend/ frontend_bundle.php frontend_layout.blade.php frontend_index_controller.php frontend_index.blade.php ... Submodule Group of pages within a module with its own embedded layout. Examples: settings within frontend, reports within admin Rule: If pages within a module need their own layout and common navigation, create a submodule. Created with: rsx:app:submodule:create Structure: rsx/app/frontend/settings/ frontend_settings_layout.blade.php frontend_settings.scss frontend_settings_index_controller.php ... Feature CRUD page group for a specific entity or concept. Examples: clients, tasks, users, projects Rule: If pages perform CRUD operations on a single entity type, they are a feature group. Created with: rsx:app:module:feature:create rsx:app:submodule:feature:create Structure: rsx/app/frontend/clients/ frontend_clients_controller.php frontend_clients.blade.php frontend_clients.js frontend_clients.scss Subfeature Individual CRUD operation within a feature. Examples: edit, view, delete, export Rule: Each distinct operation on an entity is a subfeature. Created with: rsx:app:submodule:subfeature:create Structure: rsx/app/frontend/settings/profile/edit/ frontend_settings_profile_edit_controller.php frontend_settings_profile_edit.blade.php frontend_settings_profile_edit.js frontend_settings_profile_edit.scss EXAMPLES Basic Module with Feature Structure: frontend/clients/edit Hierarchy: module, feature, subfeature Commands: php artisan rsx:app:module:create frontend php artisan rsx:app:module:feature:create frontend clients (edit subfeature created automatically with clients feature) Module with Submodule Structure: frontend/settings/profile/edit Hierarchy: module, submodule, feature, subfeature Commands: php artisan rsx:app:module:create frontend php artisan rsx:app:submodule:create frontend settings php artisan rsx:app:submodule:feature:create frontend settings profile php artisan rsx:app:submodule:subfeature:create frontend settings profile edit Simple Admin Module Structure: admin/sites Hierarchy: module, feature Commands: php artisan rsx:app:module:create admin php artisan rsx:app:module:feature:create admin sites DIRECTORY STRUCTURE Module Level rsx/app/{module}/ {module}_bundle.php - Asset bundle definition {module}_layout.blade.php - Shared layout for module {module}_index_controller.php {module}_index.blade.php {module}_index.js {module}_index.scss Feature Level rsx/app/{module}/{feature}/ {module}_{feature}_controller.php {module}_{feature}.blade.php {module}_{feature}.js {module}_{feature}.scss Submodule Level rsx/app/{module}/{submodule}/ {module}_{submodule}_layout.blade.php - Embedded layout {module}_{submodule}.scss {module}_{submodule}_index_controller.php ... Subfeature Level rsx/app/{module}/{submodule}/{feature}/{subfeature}/ {module}_{submodule}_{feature}_{subfeature}_controller.php {module}_{submodule}_{feature}_{subfeature}.blade.php {module}_{submodule}_{feature}_{subfeature}.js {module}_{submodule}_{feature}_{subfeature}.scss ROUTING Routes are automatically generated from the hierarchy: Module index: /{module} Module feature: /{module}/{feature} Submodule index: /{module}/{submodule} Submodule feature: /{module}/{submodule}/{feature} Submodule subfeature: /{module}/{submodule}/{feature}/{subfeature} Controllers use #[Route] attributes to define routes: #[Route('/{module}/{feature}', name: 'module.feature.index')] public static function index(Request $request, array $params = []) DECISION GUIDE When creating new pages, ask: 1. Does it share a layout with existing pages? YES -> Add to existing module NO -> Create new module 2. Does it need its own layout within a module? YES -> Create submodule NO -> Create feature in module 3. Is it a CRUD operation group? YES -> Create feature NO -> May need submodule or different organization 4. Is it a single CRUD operation? YES -> Create subfeature NO -> Create feature with multiple subfeatures COMMON MISTAKES Creating Module Instead of Feature WRONG: php artisan rsx:app:module:create tasks RIGHT: php artisan rsx:app:module:feature:create frontend tasks Reason: tasks shares the frontend layout, so it's a feature not a module. Creating Feature Before Module WRONG: php artisan rsx:app:module:feature:create tasks edit RIGHT: php artisan rsx:app:module:create frontend php artisan rsx:app:module:feature:create frontend tasks Error: "Module 'tasks' does not exist" Solution: Create the module first, then add features to it. Confusing Submodule with Feature Submodule: Has embedded layout, groups related features Feature: CRUD page group, uses parent layout Use submodule for: Settings, Reports, Admin sections Use feature for: Clients, Tasks, Users, Projects NAMING CONVENTIONS All names use lowercase with underscores only: [a-z_]+ Valid: frontend, client_portal, user_management Invalid: Frontend, client-portal, userManagement, User_Management FILE NAMING All files follow predictable patterns: Controller: {prefix}_controller.php View: {prefix}.blade.php JavaScript: {prefix}.js SCSS: {prefix}.scss Layout: {prefix}_layout.blade.php Bundle: {prefix}_bundle.php Where prefix is: {module}_{submodule}_{feature}_{subfeature} (omitting parts not applicable) SEE ALSO rsx_architecture(3), routing(3), bundle_api(3), controller(3)