FuseCore Modular Architecture
Agent Workflow (MANDATORY)
Before ANY implementation in FuseCore project, use TeamCreate to spawn 3 agents:
-
fuse-ai-pilot:explore-codebase - Analyze existing modules in /FuseCore/
-
fuse-ai-pilot:research-expert - Verify Laravel 12 patterns via Context7
-
fuse-laravel:laravel-expert - Apply Laravel best practices
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
FuseCore is a Modular Monolith architecture for Laravel 12 with React 19 integration.
Component Purpose
Module Self-contained feature (User, Dashboard, Blog)
Auto-Discovery Automatic registration via module.json
Traits HasModule for resource loading
Contracts ModuleInterface , ReactModuleInterface
React Integration Isolated React per module
i18n Multi-language support (FR/EN/DE/IT/ES)
Critical Rules
-
All code in /FuseCore/{Module}/
-
Never in /app/
-
One module.json per module - Required for discovery
-
ServiceProvider per module - Use HasModule trait
-
Files < 100 lines - Split at 90 lines (SOLID)
-
Interfaces in /App/Contracts/
-
Never in components
-
Migrations in module - /Database/Migrations/
-
Routes in module - /Routes/api.php
Architecture Overview
FuseCore/ ├── Core/ # Infrastructure (priority 0) │ ├── App/ │ │ ├── Contracts/ # ModuleInterface, ReactModuleInterface │ │ ├── Services/ # ModuleDiscovery, RouteAggregator │ │ ├── Traits/ # HasModule, HasModuleDatabase │ │ └── Providers/ # FuseCoreServiceProvider │ ├── Config/fusecore.php │ └── module.json │ ├── User/ # Auth module │ ├── App/Models/ # User.php, Profile.php │ ├── Config/ # Module config (sanctum.php, etc.) │ ├── Database/Migrations/ │ ├── Resources/React/ # Isolated React │ ├── Routes/api.php │ └── module.json # dependencies: [] │ └── {YourModule}/ # Your new module ├── App/ │ ├── Models/ │ ├── Http/Controllers/ │ ├── Services/ │ └── Providers/{YourModule}ServiceProvider.php ├── Config/ # Module-specific config ├── Database/Migrations/ ├── Resources/React/ ├── Routes/api.php └── module.json # dependencies: ["User"]
Reference Guide
Architecture
Topic Reference When to consult
Overview architecture.md Understanding FuseCore design
Module Structure module-structure.md Directory organization
Auto-Discovery module-discovery.md How modules are loaded
module.json module-json.md Module configuration
Implementation
Topic Reference When to consult
Contracts contracts.md ModuleInterface, ReactModuleInterface
Traits traits.md HasModule, HasModuleDatabase
ServiceProvider service-provider.md Module registration
Routes routes.md API routing
Resources
Topic Reference When to consult
React Integration react-integration.md Frontend per module
Migrations migrations.md Database per module
i18n i18n.md Multi-language setup
Guides
Topic Reference When to consult
Creating Module creating-module.md Step-by-step guide
Templates (Code Examples)
Template Purpose
module.json.md Module configuration
ServiceProvider.php.md Module service provider
Controller.php.md API controller
Model.php.md Eloquent model
Migration.php.md Database migration
ReactStructure.md React module structure
ApiRoutes.php.md API routes file
Resource.php.md API Resource
Request.php.md Form Request
Service.php.md Business logic service
Quick Reference
Create New Module
1. Create directory structure
mkdir -p FuseCore/{ModuleName}/{App/{Models,Http/Controllers,Services,Providers},Database/Migrations,Resources/React,Routes}
2. Create module.json
3. Create ServiceProvider with HasModule trait
4. Create routes/api.php
5. Run: php artisan fusecore:cache-clear
module.json
{ "name": "ModuleName", "version": "1.0.0", "enabled": true, "isCore": false, "dependencies": ["User"] }
ServiceProvider
class ModuleNameServiceProvider extends ServiceProvider { use HasModule;
public function boot(): void
{
$this->loadModuleMigrations();
}
}
Routes
Route::middleware(['api', 'auth:sanctum'])->group(function () { Route::apiResource('items', ItemController::class); });
Module Checklist
-
/FuseCore/{Module}/ directory created
-
module.json with name, version, dependencies
-
{Module}ServiceProvider.php with HasModule trait
-
Routes in /Routes/api.php
-
Migrations in /Database/Migrations/
-
Models in /App/Models/
-
Controllers in /App/Http/Controllers/
-
React in /Resources/React/ (if needed)
-
i18n in /Resources/React/i18n/locales/
SOLID Compliance
Rule FuseCore Implementation
Single Responsibility One module = one feature
Open/Closed Extend via ModuleInterface
Liskov Substitution ReactModuleInterface extends ModuleInterface
Interface Segregation Separate contracts
Dependency Inversion Inject via ServiceProvider
File limits: All files < 100 lines. Split at 90.
Naming Conventions
Type Convention Example
Module folder PascalCase BlogPost
module.json name PascalCase "name": "BlogPost"
ServiceProvider {Module}ServiceProvider
BlogPostServiceProvider
Controller {Resource}Controller
PostController
Model Singular Post
Migration create_{table}_table
create_posts_table
Routes file api.php
Always api.php