Arquitectura general
Objetivo
Explicar cómo está construido sy-energy por dentro: qué capas tiene, dónde vive cada tipo de código y qué implicaciones operativas tiene su diseño.
Audiencia
Desarrollo interno y soporte técnico.
Estado documental
- Estado: Borrador
- Última actualización: 2026-08-02
- Owner: Pendiente
- SME requerido: arquitectura y desarrollo
- Fuente resumida: estructura de código, configuración de servicios, colas y despliegue.
Qué es sy-energy
El sistema central del ecosistema. Administra clientes, centros de carga, contratos y demanda; procesa los Estados de Cuenta Diarios de CENACE; calcula el costo de la energía por centro de carga; y genera los estados de cuenta y los CFDI que se entregan al cliente y se cargan al portal SIM.
Todos los demás sistemas del ecosistema existen para alimentarlo o para extenderlo.
Stack
| Capa | Tecnología |
|---|---|
| Lenguaje | PHP 8.5 |
| Framework | Laravel 13 |
| Vistas | Blade + Laravel Mix |
| Frontend | Vue 3, Bootstrap 4, Tailwind, DataTables, Chart.js |
| Base de datos principal | MySQL |
| Bases de datos secundarias | MongoDB (precios del MEM), SQL Server (integración externa) |
| Caché y sesiones | Redis |
| Colas | AWS SQS (FIFO y estándar) y colas en base de datos |
| Almacenamiento | AWS S3 |
| dompdf | |
| Excel | Maatwebsite Excel |
| Despliegue | Deployer |
Multi-participante
sy-energy no es una instalación única. Se despliega una instancia por participante del mercado, cada una con:
- su propio despliegue y directorio en el servidor;
- su propia base de datos;
- su propio juego de colas SQS, nombradas por código de participante;
- sus propias credenciales de CENACE y de Factura.com.
Es la decisión de arquitectura con más impacto operativo del sistema. Implica que:
- un comando ejecutado en la instancia equivocada produce datos incorrectos sin reportar error;
- un incidente hay que acotarlo siempre a un participante;
- hay reglas de negocio que difieren entre participantes — por ejemplo, algunos cálculos se excluyen deliberadamente para ciertos participantes.
Organización del código
Conviven dos estilos, resultado de una migración progresiva hacia una estructura por dominios:
app/ capa histórica de Laravel
src/ capa por dominios (DDD), namespace SyEnergy\src/ — dominios
Es donde vive la lógica de negocio nueva. Cada dominio agrupa sus acciones, constructores de consultas, validadores y constantes.
| Dominio | Responsabilidad |
|---|---|
ChargeCenter | Centros de carga y sus consultas. |
Demand | Demanda eléctrica. |
PassThrough | Cálculos de costo pass-through: MDA, MTR, congestión, distribución, capacidad. |
Cfdi | Comprobantes fiscales. |
FacturaCom | Integración con el proveedor de timbrado. |
Orders | Órdenes y documentos generados. |
Cels | Certificados de Energías Limpias. |
CfeTx | Integración de transacciones CFE. |
Reports | Reportes exportables. |
Services | Servicios de dominio compartidos. |
General / Api / Redirect | Soporte transversal. |
app/ — capa Laravel
| Carpeta | Contenido |
|---|---|
Console/Commands | Los comandos operativos. Organizados por función: Calculate, PassThrough, Dispatch, Files, Bots, Demand, Report, Sync. |
Jobs | Trabajos de cola, incluidos los de despacho y los de respuesta de bots. |
Services | Integraciones: AWS, bots, adaptador de sincronización de demanda. |
Strategy | Estrategias por tipo de producto y tipo de documento. |
Builder | Constructores de estados de cuenta: uno para costo fijo, otro para pass-through. |
Tools | Utilidades por dominio funcional. |
Libraries | Reglas externas fijas, como el catálogo de CFDI de CENACE. |
Http | Controladores, requests y middleware. |
Raíz de app/ | Modelos Eloquent históricos (CentroCarga, Contract, Factura, Participante, Order…). Los nombres mezclan español e inglés. |
Al buscar código
La lógica de negocio nueva está en src/Domain/. Los modelos y los comandos están en app/. Si un cálculo no aparece donde se espera, suele estar en una Action del dominio correspondiente, invocada desde un comando.
Cómo se ejecuta el trabajo
Tres caminos, con implicaciones distintas para el diagnóstico:
| Camino | Cómo se dispara | Qué hay que verificar si falla |
|---|---|---|
| Interfaz web | Usuario en el navegador | Logs de la aplicación. |
| Comando de consola | Scheduler o ejecución manual | Que el cron esté vivo y el log de la tarea. |
| Cola | Un comando despacha; un worker procesa | Que el worker esté arriba. El comando que despacha reporta éxito aunque nadie procese el trabajo. |
El tercer caso es la fuente más frecuente de confusión operativa: encolar no es procesar.
Conexiones de cola configuradas: sqsfifo, sqscustom, database, redis, sync. Las colas FIFO se usan donde el orden importa, como el balance de CENACE y la sincronización de ECD.
Integraciones
Resumen; el detalle está en Integraciones externas.
| Sistema externo | Para qué | Dirección |
|---|---|---|
| CENACE (API) | Descarga de ECD y documentos | Entrada |
| CENACE (portal SIM) | Carga de facturas, REA, FOP — vía bots | Ambas |
| Factura.com | Timbrado de CFDI | Salida |
| MEM | Precios de nodos y zonas de carga | Entrada |
| CFE / CFE TX | Tarifas y mediciones de alta tensión | Entrada |
| Servicio de demanda | Demanda de centros de carga | Entrada |
| AWS (SQS, S3) | Transporte y almacenamiento | Ambas |
Riesgos y gaps
- La coexistencia de
app/ysrc/significa que hay lógica equivalente en dos estilos; no está documentado qué se migra y qué se queda. - Los modelos históricos mezclan español e inglés en nombres de tabla y columna, lo que dificulta la lectura de consultas.
- No está documentada la arquitectura de red ni el dimensionamiento del servidor.
- Falta un diagrama de entidades del modelo de datos.
- No está documentado qué diferencias de configuración existen entre instancias de participante, más allá de las colas.
Próxima revisión
Al documentar el modelo de datos.