Mañuti
Mañuti / Docs v1.0
resources/views/pages/frontend/docs/arquitectura.md
Última modificación: 27 Oct, 2026

Visión General de la Arquitectura de Mañuti

Mañuti (FrameDev v12) es un framework empresarial polimórfico de alto rendimiento construido sobre el ecosistema Laravel 12/13 (PHP 8.5 NTS). Ha sido concebido desde sus cimientos bajo los principios de Arquitectura Limpia (Clean Architecture), Diseño Guiado por el Dominio (DDD) y cumplimiento estricto de los estándares internacionales de seguridad de la información y privacidad de datos ISO/IEC 27001 e ISO/IEC 27701.

La plataforma resuelve el dilema clásico entre la agilidad de desarrollo de un monolito y la resiliencia operativa de una arquitectura distribuida: puede aprovisionarse como una instancia única autónoma o desacoplarse elásticamente en clústeres de alta disponibilidad sobre Bare-Metal, contenedores Docker, Docker Swarm o Kubernetes.

1. Principios Rectores de Ingeniería

+---------------------------------------------------------------------------------------+
|                                  MAÑUTI FRAMEWORK CORE                                |
+---------------------------------------------------------------------------------------+
|  1. Persistencia Tri-Motor  | SQL Relacional + NoSQL BSON + In-Memory RAM + S3 MinIO   |
|  2. Stateless Web Tier      | Servidores web sin estado; sesiones y archivos fuera    |
|  3. Red Zero-Trust & UFW    | Aislamiento perimetral estricto punto a punto           |
|  4. Seguridad por Capas     | RBAC Aditivo, Kill Switch WebSocket, 2FA TOTP, PII Cifrado|
|  5. Tiempo Real & Colas     | Laravel Reverb (Event Loop) + Horizon Worker Daemons    |
|  6. Puente Políglota IPC    | Subprocesos Python 3 / Graphviz orquestados en Kernel   |
|  7. Calidad Certificada     | Larastan Nivel 8 estricto + Pruebas SQLite In-Memory    |
+---------------------------------------------------------------------------------------+
  1. Desacoplamiento de Estado (Stateless Application Tier): Los nodos de aplicación web (PHP-FPM/Nginx) no almacenan sesiones, cachés ni archivos en discos locales. Cualquier nodo puede destruirse o escalarse sin degradar la experiencia del usuario.
  2. Cero Bloqueo de I/O en HTTP: Las tareas de auditoría forense, envíos de correo, generación de diagramas y difusión de WebSockets se delegan a workers asíncronos en segundo plano.
  3. Defensa en Profundidad (Defense-in-Depth): La seguridad opera en cinco capas independientes: Red (UFW), Transporte (TLS/HSTS), Cabeceras HTTP (CSP), Autorización (RBAC) y Criptografía en Reposo (AES-256).
  4. API Políglota de Servicio Único: Una única capa de negocio (CatalogoService) expone datos concurrentemente en RESTful JSON y SOAP XML/WSDL.

2. Diagrama de Arquitectura Global del Sistema

El siguiente diagrama modela la interacción entre las capas de acceso público, procesamiento de aplicación, orquestación en tiempo real y la persistencia híbrida:

flowchart TB
    %% Tráfico Externo
    subgraph CapaInternet ["Tráfico Externo & Clientes"]
        UserBrowser["Navegador Web (Desktop / Mobile)"]
        ExternalClient["Sistemas Externos / APIs / Webhooks"]
    end

    %% Capa Ingress
    subgraph CapaIngress ["1. Capa de Acceso & Balanceo (DMZ)"]
        LB["Nginx Load Balancer / Reverse Proxy<br>(Terminación TLS / Cert-Manager / WSS Proxy)"]
    end

    %% Capa de Aplicación
    subgraph CapaApp ["2. Capa de Cómputo & Aplicación (Stateless)"]
        WebNodes["Clúster Web PHP 8.5-FPM<br>(Web-01, Web-02, Web-N)"]
        HorizonWorkers["Clúster Workers Laravel Horizon<br>(Procesamiento Asíncrono & Daemons)"]
        ReverbServer["Servidor WebSockets Laravel Reverb<br>(Daemon Event Loop Puerto 8080)"]
        PythonBridge["Motor Políglota Python 3<br>(Framedev Architect & Graphviz IPC)"]
    end

    %% Capa de Persistencia Tri-Motor + S3
    subgraph CapaDatos ["3. Persistencia Tri-Motor + Object Storage"]
        MariaDB[("MariaDB Clúster / Galera<br>[SQL Relacional / ACID / RBAC / Batches]")]
        RedisServer[("Redis 7.0 In-Memory Clúster<br>[Sesiones / Caché / Colas / Pub-Sub]")]
        MongoDBServer[("MongoDB 7.0 NoSQL<br>[Auditoría Forense Inmutable / System Errors]")]
        MinIOS3[("MinIO Object Storage S3<br>[Avatares / Exportaciones ARCO / SVGs]")]
    end

    %% Flujos de Red
    UserBrowser -->|"HTTPS:443"| LB
    ExternalClient -->|"HTTPS:443 (REST / SOAP / Webhooks)"| LB
    UserBrowser -.->|"WSS:443 (Túnel WebSocket Persistente)"| LB

    LB -->|"HTTP:80 (Proxy Pass Balanceado)"| WebNodes
    LB -.->|"TCP:8080 (WSS Upgrade Proxy)"| ReverbServer

    WebNodes -->|"SQL (TCP:3306)"| MariaDB
    WebNodes -->|"Session / Cache (TCP:6379)"| RedisServer
    WebNodes -->|"PutObject (TCP:9000)"| MinIOS3
    WebNodes -->|"HTTP Push Events:8080"| ReverbServer
    WebNodes -.->|"Dispatch Jobs"| RedisServer

    HorizonWorkers -->|"Pop Jobs"| RedisServer
    HorizonWorkers -->|"Subprocess IPC / Stdio"| PythonBridge
    HorizonWorkers -->|"BSON Insert (TCP:27017)"| MongoDBServer
    HorizonWorkers -->|"SQL State (TCP:3306)"| MariaDB
    HorizonWorkers -->|"Stream S3 (TCP:9000)"| MinIOS3

    ReverbServer -->|"Redis Pub/Sub (TCP:6379)"| RedisServer
    PythonBridge -->|"SVG Vectorial Output"| MinIOS3

3. Modelo de Persistencia Tri-Motor + Object Storage S3

Mañuti utiliza cada motor de persistencia exclusivamente para la carga de trabajo donde sus algoritmos son óptimos:

+-------------------+----------------------+--------------------------------------------------+
| MOTOR             | TECNOLOGÍA           | RESPONSABILIDAD ARQUITECTÓNICA EXCLUSIVA         |
+-------------------+----------------------+--------------------------------------------------+
| SQL Relacional    | MariaDB / MySQL /    | * Integridad transaccional ACID (usuarios, roles)|
|                   | PostgreSQL           | * Tablas pivote N:M y restricciones foráneas     |
|                   |                      | * Estado persistente de lotes (job_batches)      |
|                   |                      | * Registro forense de fallos (failed_jobs)       |
+-------------------+----------------------+--------------------------------------------------+
| NoSQL Documental  | MongoDB 7.0+         | * Auditoría forense no estructurada (auditoria)  |
|                   |                      | * Captura de payloads JSON sin límite de esquema |
|                   |                      | * Centralización de errores (FallbackGroupHandler|
|                   |                      | * Trazabilidad inmutable sin bloqueos de fila    |
+-------------------+----------------------+--------------------------------------------------+
| In-Memory Engine  | Redis 7.0+           | * Sesiones de usuario ultraligeras (520 Bytes)   |
|                   |                      | * Almacén de caché con Tags (catalogos, config)  |
|                   |                      | * Semáforos y bloqueos atómicos (Cache::lock)    |
|                   |                      | * Broker de transporte de colas (Horizon)        |
|                   |                      | * Bus de distribución Pub/Sub para Reverb        |
+-------------------+----------------------+--------------------------------------------------+
| Object Storage S3 | MinIO / AWS S3       | * Avatares y activos multimedia de usuarios      |
|                   |                      | * Paquetes de exportación ARCO protegidos        |
|                   |                      | * Diagramas vectoriales SVG de arquitectura      |
+-------------------+----------------------+--------------------------------------------------+

4. Las 7 Topologías de Despliegue Certificadas

La infraestructura de Mañuti es polimórfica: el mismo código fuente se empaqueta y despliega sobre siete arquitecturas físicas o virtualizadas sin refactorización:

  1. Monolito en Servidor Único: LEMP Stack completo optimizado en Ubuntu 24.04 con Supervisor y demonios independientes.
  2. Bare Metal Distribuido: Clúster de 8 nodos dedicados segregados por rol y coordinados por el Bastión CD Automatizado (deploy.sh).
  3. Red Zero-Trust & Políticas UFW: Matriz de filtrado de paquetes con denegación universal por defecto y túneles punto a punto.
  4. Docker & Doble Red Zero-Trust: Golden Image multi-stage (PHP 8.5 + Node 20 + Python 3) distribuida en GitHub Container Registry (ghcr.io) con redes aisladas frontend_net y backend_net.
  5. Docker Swarm Clúster: Orquestación multi-nodo con redes Overlay encriptadas, Secrets, Configs y persistencia NFS compartida.
  6. Kubernetes Bare-Metal (K8s): Clúster de 5 nodos aprovisionado con kubeadm v1.31, balanceo MetalLB en Capa 2, Ingress-NGINX, cert-manager y NFS Subdir Provisioner.
  7. Minikube Local & Helm CSI: Entorno local de desarrollo K8s con túneles SSH hacia bases de datos y observabilidad Prometheus/Grafana.
  8. Contenedores Linux (Incus/LXC): Micro-instancias en Ubuntu 26.04 con interfaces de red de alto rendimiento en modo macvlan.

5. Seguridad Bancaria y Cumplimiento Normativo (ISO 27001 / 27701)

El marco de seguridad de Mañuti supera auditorías corporativas mediante controles nativos:

[HTTP Request] ---> [SecurityHeaders: CSP / HSTS / nosniff / SAMEORIGIN]
                            |
                            v
               [PreventBackHistory: no-store / bfcache]
                            |
                            v
                [CheckSystemMaintenance: Bypass Admin 503]
                            |
                            v
              [CheckActiveSession: Single Session Kill Switch]
                            |
                            v
               [CheckPasswordExpiration: Cuarentena 90 días]
                            |
                            v
            [CheckForcedPasswordChange: must_change_password]
                            |
                            v
             [CheckPendingDocuments: Cuarentena LegalTech]
                            |
                            v
                 [CheckTwoFactor: Desafío TOTP RFC 6238]
                            |
                            v
                [can:slug.permiso: Gate RBAC Aditivo]

Controles Destacados

6. Procesamiento Asíncrono, Colas y Tiempo Real

La reactividad del sistema se estructura en dos motores complementarios:

A. Orquestación de Colas con Laravel Horizon

  • Colas Híbridas: Transporte de trabajos en Redis y persistencia de fallos (failed_jobs) y lotes (job_batches) en MariaDB.
  • Resurrección de Fallos: Análisis forense de excepciones y reactivación manual mediante php artisan queue:retry.
  • Auto-Balancing: Supervisores elásticos que ajustan workers según el tráfico de colas como imports, exports y auditoria.

B. Servidor WebSockets con Laravel Reverb

  • Servidor Nativo Reverb: Demonio asíncrono en puerto 8080 con escalamiento horizontal mediante Redis Pub/Sub.
  • Canales Privados Seguros: Expulsión remota de operadores (user.{id}), monitor de concurrencia (admin.sessions) y visualización de auditoría en vivo (admin.updates).

7. Puente Políglota IPC: Python 3 & Graphviz (Framedev Architect)

Mañuti rompe los límites de PHP implementando un Puente Inter-Lenguaje de Alto Rendimiento ejecutado a través de subprocesos en Kernel:

[Controlador Web] --(Async Job)--> [Horizon Worker]
                                           |
                              (Process::run / POSIX Pipes)
                                           |
                                           v
                       [Motor Python 3 / full_flow_mapper.py]
                                           |
                        +------------------+------------------+
                        |                                     |
                        v                                     v
         [Análisis de Código AST / Regex]       [Compilación Graphviz DOT]
         * Rutas HTTP web.php                   * Nodos y relaciones
         * Controladores y subcarpetas          * Formato SVG vectorial
         * Vistas Blade (view())                * Atributos de enlace URL
         * Modelos Eloquent y relaciones        * Inyección XML en DOM
                        |                                     |
                        +------------------+------------------+
                                           |
                                           v
                          [Subida Directa a MinIO S3]

Este diseño evita el overhead de microservicios HTTP externos y demuestra la capacidad de Mañuti para orquestar motores en Python, Go o Rust para cómputo intensivo.

8. Capa de Servicios, APIs y Movilidad Offline-First

El framework implementa una arquitectura desacoplada para clientes heterogéneos:

  • API Políglota Dual (REST + SOAP): Capa de servicio unificada (CatalogoService) expuesta simultáneamente en endpoints RESTful (JSON) y servicios SOAP (XML/WSDL dinámico generado con Laminas).
  • Seguridad con Sanctum & Webhooks HMAC: Autenticación mediante tokens personales Bearer y validación de webhooks entrantes con firmas criptográficas X-Hub-Signature-256.
  • Movilidad Híbrida Offline-First: Detección de dispositivos mediante el fork de Mobile-Detect, enrutamiento inteligente y soporte para aplicaciones standalone con Framework7 + Capacitor + Dexie.js (IndexedDB).

9. Métricas de Rendimiento y Certificación de Calidad

La arquitectura ha sido sometida a pruebas automatizadas de regresión, estrés y análisis estático estricto:

  • Análisis Estático: Certificado bajo Larastan Nivel 8 (máxima rigurosidad de tipado fuerte, análisis de nulabilidad y cero errores de relación).
  • Pruebas Unitarias y de Integración: Suite completa en PHPUnit sobre base de datos SQLite en Memoria RAM con factories autónomas y aislamiento de middlewares.
  • Prueba de Carga y Estrés (k6 Benchmarking):
    • Latencia P95: 41.98 ms bajo carga concurrente sostenida de 50 VUs.
    • Tasa de Error: 0.00% (708 peticiones exitosas consecutivas).
    • Consumo de Memoria: 520 Bytes por sesión activa en Redis.

10. Mapa de Navegación Arquitectónica

Explore a profundidad cada subsistema a través de la documentación especializada:

Arquitecturas Certificadas

Seguridad, Core y Componentes

Edita este documento en >> arquitectura.md
← Volver a la Landing Page