fusecore

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.

FuseCore Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation in FuseCore project, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing modules in /FuseCore/
2. fuse-ai-pilot:research-expert - Verify Laravel 13 patterns via Context7
3. 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

1. All code in /FuseCore/{Module}/ - Never in /app/
2. One module.json per module - Required for discovery
3. ServiceProvider per module - Use HasModule trait
4. Files within FUSE_SOLID_MAX_LINES - Split larger files (SOLID)
5. Interfaces in /App/Contracts/ - Never in components
6. Migrations in module - /Database/Migrations/
7. 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 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)