Fusecore

---
name: fusecore
description: Use when creating modules, understanding FuseCore structure, or implementing features in a FuseCore modular-monolith Laravel project.
versions:
  laravel: "13.0"
  php: "8.3"
  react: "19"
  typescript: "7.0"
user-invocable: true
references: references/architecture.md, references/module-structure.md, references/module-discovery.md, references/module-json.md, references/contracts.md, references/traits.md, references/service-provider.md, references/react-integration.md, references/routes.md, references/migrations.md, references/i18n.md, references/creating-module.md
related-skills: solid-php, laravel-permission, laravel-api
---

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

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 < 100 lines** - Split at 90 lines (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](references/architecture.md) | Understanding FuseCore design |
| **Module Structure** | [module-structure.md](references/module-structure.md) | Directory organization |
| **Auto-Discovery** | [module-discovery.md](references/module-discovery.md) | How modules are loaded |
| **module.json** | [module-json.md](references/module-json.md) | Module configuration |

### Implementation

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Contracts** | [contracts.md](references/contracts.md) | ModuleInterface, ReactModuleInterface |
| **Traits** | [traits.md](references/traits.md) | HasModule, HasModuleDatabase |
| **ServiceProvider** | [service-provider.md](references/service-provider.md) | Module registration |
| **Routes** | [routes.md](references/routes.md) | API routing |

### Resources

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **React Integration** | [react-integration.md](references/react-integration.md) | Frontend per module |
| **Migrations** | [migrations.md](references/migrations.md) | Database per module |
| **i18n** | [i18n.md](references/i18n.md) | Multi-language setup |

### Guides

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Creating Module** | [creating-module.md](references/creating-module.md) | Step-by-step guide |

---

### Templates (Code Examples)

| Template | Purpose |
|----------|---------|
| [module.json.md](references/templates/module.json.md) | Module configuration |
| [ServiceProvider.php.md](references/templates/ServiceProvider.php.md) | Module service provider |
| [Controller.php.md](references/templates/Controller.php.md) | API controller |
| [Model.php.md](references/templates/Model.php.md) | Eloquent model |
| [Migration.php.md](references/templates/Migration.php.md) | Database migration |
| [ReactStructure.md](references/templates/ReactStructure.md) | React module structure |
| [ApiRoutes.php.md](references/templates/ApiRoutes.php.md) | API routes file |
| [Resource.php.md](references/templates/Resource.php.md) | API Resource |
| [Request.php.md](references/templates/Request.php.md) | Form Request |
| [Service.php.md](references/templates/Service.php.md) | Business logic service |

---

## Quick Reference

### Create New Module

```bash
# 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

```json
{
    "name": "ModuleName",
    "version": "1.0.0",
    "enabled": true,
    "isCore": false,
    "dependencies": ["User"]
}
```

### ServiceProvider

```php
class ModuleNameServiceProvider extends ServiceProvider
{
    use HasModule;

    public function boot(): void
    {
        $this->loadModuleMigrations();
    }
}
```

### Routes

```php
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`.

```php
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:

```json
{
  "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)