<objective> FuseCore is a modular-monolith architecture for Laravel 13 with React 19 integration, built on auto-discovery (module.json), SOLID principles, and per-module isolation (models, migrations, routes, React resources, i18n). Covers creating new modules, understanding the FuseCore directory structure and module-discovery mechanism, and implementing features inside FuseCore projects — module contracts, traits (HasModule), service providers, and cross-module dependency declaration. </objective>

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 < 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 |

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 100 lines per file (split into sub-modules or Services)
Share migrations between modules (each module owns its tables)