Sistema de API Gateway Modular con Laravel 11

El Desafío

Cuando me uní al proyecto LC backend en Grupo Antyr, nos enfrentábamos a un desafío arquitectónico complejo: necesitábamos un sistema capaz de orquestar más de 10 dominios de negocio diferentes (créditos, inventario, ventas, clientes, pagos, etc.) de manera que cada uno pudiera desplegarse de forma independiente sin afectar al resto del sistema.

El problema principal era que el sistema legacy tenía todos los dominios entrelazados, haciendo imposible realizar cambios sin riesgo de romper funcionalidades en otros módulos. Un deploy simple podía tomar horas de pruebas y coordinación.

El Problema de la Documentación

Pero había otro reto igual de crítico: mantener la documentación actualizada para múltiples equipos. El equipo de frontend, los equipos de mobile, y varios socios internacionales consumían estas APIs, y cada cambio generaba:

❌ Reuniones interminables para explicar cambios en endpoints
❌ Documentación desactualizada en wikis y Postman collections
❌ Tickets de soporte por “la API no funciona” (cuando era solo un campo renombrado)
❌ Fricción en el desarrollo por falta de contratos claros

Necesitábamos una solución que:

Generara documentación automáticamente desde el código
Estuviera siempre sincronizada con la realidad
Se organizara por módulos para facilitar la navegación
Cumpliera con estándares OpenAPI 3.0 para interoperabilidad

La Solución: Arquitectura HMVC

Diseñamos e implementamos una arquitectura HMVC (Hierarchical Model-View-Controller) en Laravel 11 que funciona como un API Gateway modular. La idea central fue simple pero poderosa: cada dominio de negocio se comporta como un módulo autocontenido con su propia lógica, rutas, controladores y modelos.

Componentes Clave

1. Módulos Independientes Cada dominio es un módulo Laravel completo con su propia estructura:

Modules/
├── Credits/
│   ├── Routes/
│   ├── Controllers/
│   ├── Models/
│   ├── Services/
│   └── Tests/
├── Inventory/
├── Sales/
└── ...

2. Service Layer Implementé una capa de servicios robusta que maneja la lógica de negocio. Esto mantiene los controladores delgados y facilita el testing:

Services para operaciones complejas
Repositories para acceso a datos
DTOs (Data Transfer Objects) para transferencia entre capas

3. Redis para Performance Integré Redis para:

Caching inteligente de respuestas frecuentes
Almacenamiento de tokens y permisos (abilities con SHA-256)
Reducción drástica de consultas a base de datos

4. Documentación OpenAPI Automática con Scramble Personalizado

Elegimos Laravel Scramble para generar documentación OpenAPI automáticamente desde el código. El problema: Scramble de serie no soporta organización por módulos en su interfaz visual.

El Reto: Necesitábamos que la documentación mostrara endpoints agrupados por módulos (Credits, Inventory, Sales, etc.) para que los consumidores pudieran navegar fácilmente.

La Solución: Extendimos Scramble creando un custom InfoExtractor que:

// Custom InfoExtractor para módulos
class ModuleInfoExtractor extends InfoExtractor
{
    public function extract(): OpenApi
    {
        $openApi = parent::extract();
        
        // Agrupar endpoints por módulo usando tags
        foreach ($openApi->paths as $path => $pathItem) {
            $module = $this->extractModuleFromPath($path);
            foreach ($pathItem->operations() as $operation) {
                $operation->tags = [$module];
            }
        }
        
        return $openApi;
    }
    
    private function extractModuleFromPath(string $path): string
    {
        // /api/v1/credits/... → Credits
        preg_match('#/api/v1/([^/]+)/#', $path, $matches);
        return ucfirst($matches[1] ?? 'General');
    }
}

También personalizamos la vista Blade de Scramble para mostrar un sidebar con navegación por módulos:

{{-- resources/views/vendor/scramble/index.blade.php --}}
<div class="flex h-screen">
    <div class="w-64 bg-gray-900 overflow-y-auto">
        @foreach($modules as $module)
            <div class="px-4 py-2">
                <h3 class="text-teal-300 font-bold">{{ $module }}</h3>
                <ul class="text-sm text-gray-400">
                    @foreach($endpointsByModule[$module] as $endpoint)
                        <li>{{ $endpoint->method }} {{ $endpoint->path }}</li>
                    @endforeach
                </ul>
            </div>
        @endforeach
    </div>
    <div class="flex-1">
        {{-- Contenido de Scramble original --}}
    </div>
</div>

Resultado: Documentación automática, organizada por módulos, siempre actualizada.

Esto eliminó completamente la deuda técnica de documentación manual y mejoró la comunicación con socios internacionales. Los desarrolladores frontend ahora simplemente visitan /docs/api y tienen todo actualizado.

Resultados Medibles

✅ Despliegues Independientes: Ahora cada módulo se despliega sin afectar a otros
✅ Reducción de Latencia: Redis redujo consultas a BD en un 70%
✅ Tiempo de Deploy: De 3+ horas a menos de 30 minutos
✅ Documentación Actualizada: OpenAPI siempre sincronizada con el código
✅ Escalabilidad: Capacidad de agregar nuevos módulos sin modificar el core

Aprendizajes Clave

1. La Arquitectura Importa Más que el Framework

Laravel es excelente, pero la arquitectura correcta es lo que realmente escala. HMVC nos dio:

Separación de responsabilidades clara
Mantenibilidad a largo plazo
Facilidad para onboarding de nuevos developers

2. Documentación Automática No es Opcional

Scramble fue un game-changer, aunque tuvimos que extenderlo. La documentación generada automáticamente:

Siempre está actualizada
Reduce reuniones de alineación
Facilita la integración con partners

Pero el aprendizaje más importante: No tengas miedo de personalizar las herramientas. Scramble no soportaba módulos de serie, pero con un custom InfoExtractor y una vista Blade personalizada, lo adaptamos perfectamente a nuestras necesidades.

3. Redis es Tu Mejor Amigo

El caching bien implementado no solo mejora performance, también reduce costos de infraestructura y mejora la experiencia de usuario.

4. Testing desde el Inicio

Cada módulo tiene su propia suite de tests. Esto nos dio confianza para refactorizar y agregar features sin miedo.

Stack Técnico

Backend: Laravel 11 (PHP 8.2+)
Arquitectura: HMVC pattern
Cache: Redis 7.x
Documentación: OpenAPI 3.0 (Scramble)
Base de Datos: MySQL 8.0
Containerización: Docker
Testing: PHPUnit + Pest

Conclusión

Este proyecto me enseñó que la arquitectura correcta puede transformar un sistema monolítico en una plataforma modular escalable sin necesidad de microservicios completos. HMVC en Laravel nos dio el balance perfecto entre monolito y microservicios.

La clave del éxito fue:

Modularidad desde el diseño
Caching estratégico
Documentación automática
Testing exhaustivo

Si estás enfrentando problemas similares de escalabilidad en tu monolito, considera HMVC antes de saltar directamente a microservicios. A veces, la solución más simple es la correcta.

¿Preguntas sobre la implementación? No dudes en contactarme en LinkedIn o GitHub.