FuseCore Modular Architecture

FuseCore Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation in FuseCore project, launch in parallel:

1. fuse-ai-pilot:explore-codebase - Analyze existing modules in /​FuseCore/
2. fuse-ai-pilot:research-expert - Verify Laravel 12 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 12 with React 19 integration.

---

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

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

File limits: All files < 100 lines. Split at 90.

---

Naming Conventions