FuseCore Modular Architecture
Agent Workflow (MANDATORY)
Before ANY implementation in FuseCore project, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing modules in
/FuseCore/
- fuse-ai-pilot:research-expert - Verify Laravel 13 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 13 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 within
FUSE_SOLID_MAX_LINES - Split larger files (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
Implementation
Resources
Guides
Templates (Code Examples)
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 within FUSE_SOLID_MAX_LINES. Split well before it.
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 |
Laravel 13 Notes
Stack FuseCore L13
- Laravel 13 (stable 13.33) + PHP 8.3 minimum
- React 19 + TypeScript 7 (module frontend side) — TS 7.0 has no compiler API: typescript-eslint (peer
typescript <6.1.0) requires the alias "typescript": "npm:@typescript/typescript6@^6.0.2" + "@typescript/native": "npm:typescript@^7.0.2" (npx tsc = 7.0)
- Inertia 3 (
inertiajs/inertia-laravel ^3.0) for the React ↔ modules bridge
Module ServiceProvider and L13
Bindings in register(), observers/hooks in boot(). L13 reminder: instantiating a model during its own boot (new static() inside the model's boot() or a trait's boot*()) throws a LogicException.
public function register(): void
{
$this->app->bind(PostRepositoryContract::class, EloquentPostRepository::class);
}
public function boot(): void
{
Post::observe(PostObserver::class);
}
Per-module cache prefixes
L13 uses hyphens by default. For FuseCore, configuring the prefix per module via module.json remains compatible:
{
"name": "BlogPost",
"cache_prefix": "blogpost-"
}
Best Practices
DO
- One module = one complete
FuseCore/<Module>/ folder (Contracts/, Services/, Http/, Models/)
- Declare every inter-module dependency via Contracts (never concrete classes)
- Use
final readonly class for module DTOs (PHP 8.3+)
- Move all Model logic from
register() to boot()
- Prefer Inertia 3 + React 19 for modules with a UI
DON'T
- Import a class from another module without going through its Contract
- Put business logic in Controllers (extract it into a module Service)
- Instantiate a model during its own boot (
new static() inside boot() → LogicException in L13)
- Exceed the hook ceiling
FUSE_SOLID_MAX_LINES per file (split into sub-modules or Services)
- Share migrations between modules (each module owns its tables)
