ac082bce2a
Always include params in window.rsxapp to reduce state variations Add request params to window.rsxapp global Enhance module creation commands with clear nomenclature guidance Add module/submodule/feature nomenclature clarification to docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
235 lines
7.7 KiB
Plaintext
Executable File
235 lines
7.7 KiB
Plaintext
Executable File
MODULE_ORGANIZATION(3) RSX Framework Manual MODULE_ORGANIZATION(3)
|
|
|
|
NAME
|
|
Module Organization - RSX application structure and nomenclature
|
|
|
|
SYNOPSIS
|
|
php artisan rsx:app:module:create <name>
|
|
php artisan rsx:app:module:feature:create <module> <feature>
|
|
php artisan rsx:app:submodule:create <module> <submodule>
|
|
php artisan rsx:app:submodule:feature:create <module> <submodule> <feature>
|
|
php artisan rsx:app:submodule:subfeature:create <module> <submodule> <feature> <subfeature>
|
|
|
|
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 <name>
|
|
|
|
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 <module> <submodule>
|
|
|
|
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 <module> <feature>
|
|
rsx:app:submodule:feature:create <module> <submodule> <feature>
|
|
|
|
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 <module> <submodule> <feature> <subfeature>
|
|
|
|
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)
|