🐇 fireflayjs
Product Manifesto v1
Sobre Este Documento
Este manifiesto describe la tesis, dirección conceptual y filosofía de producto de fireflayjs.
No representa un roadmap cerrado ni una promesa de implementación completa.
El objetivo del documento es:
- externalizar el modelo mental del ecosistema
- definir la intención arquitectónica del proyecto
- establecer principios de diseño
- identificar capacidades núcleo no negociables
- explorar posibles direcciones evolutivas
Muchas de las ideas descritas aquí representan hipótesis, exploraciones o líneas potenciales de evolución futura.
El alcance real del proyecto evolucionará iterativamente a través de RFCs, validación técnica y experiencia práctica.
“La tesis irreducible”
La tesis central de fireflayjs es que la arquitectura frontend no debería vivir únicamente como documentación pasiva o convenciones sociales.
Los límites organizacionales, dependencias y capacidades públicas de un sistema deberían poder declararse, observarse y validarse automáticamente como parte del workflow real de desarrollo.
fireflayjs explora una dirección donde la arquitectura frontend se convierte en metadata ejecutable, observable y gobernable.
Executable Architecture Contracts for Frontend Platforms
Un sistema de observabilidad y contratos arquitectónicos embebido en el workflow de desarrollo.
Para equipos que desarrollan plataformas enterprise complejas (como entornos multitenant masivos) sin la presencia constante de un arquitecto dedicado, fireflayjs actúa como una capa de gobernanza arquitectónica y asistencia estructural:
- cómo se organiza el proyecto global
- cómo fluyen las dependencias entre módulos
- cómo evolucionan los límites arquitectónicos en el tiempo
- cómo distintas partes pueden evolucionar independientemente sin perder coherencia sistémica
- cómo las decisiones arquitectónicas impactan la estructura del sistema en tiempo real
Estado Actual del Proyecto
fireflayjs se encuentra actualmente en una etapa experimental temprana.
El foco inicial del ecosistema está puesto en:
- contratos arquitectónicos declarativos
- análisis de dependencias
- observabilidad arquitectónica
- boundary arquitectónico linting
- generación de metadata para CI/CD (
affected.json)
Este manifiesto describe principalmente una visión conceptual de largo plazo, no el estado actual de implementación.
El Dolor Enterprise
En equipos grandes con desarrollo paralelo, la arquitectura suele vivir en documentación estática, convenciones implícitas y conocimiento tribal.
El resultado es architecture drift:
- módulos que comienzan a acoplarse silenciosamente
- pérdida de claridad sobre ownership y boundaries
- CI/CD incapaz de entender el impacto real de los cambios
- degradación progresiva de la estructura organizacional del sistema
Este problema se vuelve especialmente visible en plataformas frontend masivas:
- monorepos enterprise
- super apps
- marketplaces universales
- aplicaciones React Native compartidas entre decenas de equipos
A medida que múltiples squads evolucionan el mismo ecosistema, el acoplamiento invisible termina afectando:
- estabilidad
- despliegues
- autonomía organizacional
- velocidad de evolución
fireflayjs explora cómo transformar esas relaciones implícitas en contratos explícitos y observables.
Qué es fireflayjs
fireflayjs explora una capa de gobernanza arquitectónica y asistencia estructural para plataformas frontend complejas.
Su foco está en:
- contratos arquitectónicos ejecutables
- observabilidad estructural
- análisis de dependencias
- inteligencia de impacto
- feedback arquitectónico contextual
- asistencia en decisiones arquitectónicas en tiempo real
- reconocimiento de patrones arquitectónicos emergentes
- evolución modular progresiva
fireflayjs no solo analiza la arquitectura del sistema, sino que ayuda a interpretarla mientras se escribe código, haciendo visibles sus implicancias sin imponer restricciones.
Qué NO busca ser
fireflayjs no busca reemplazar:
- frameworks frontend
- monorepo runners
- package managers
- pipelines de CI/CD
- herramientas de deployment runtime
Tampoco intenta imponer:
- una arquitectura interna única
- patrones de implementación específicos
- una filosofía cerrada de diseño de módulos
El foco del ecosistema está en gobernanza estructural, observabilidad arquitectónica y asistencia contextual.
Non-Negotiable Product Capabilities
Independientemente de cómo evolucione el ecosistema, fireflayjs debe siempre:
- Permitir declarar explícitamente la estructura arquitectónica del sistema
- Comprender relaciones entre módulos y boundaries
- Generar observabilidad arquitectónica accionable
- Producir feedback contextual sobre impacto estructural
- Reconocer patrones arquitectónicos emergentes en el código
- Explicar trade-offs de decisiones arquitectónicas sin imponerlas
- Mantener independencia respecto al framework y tooling de build
- Permitir adopción progresiva e incremental
Estas capacidades constituyen el núcleo irreducible del proyecto.
Principios Técnicos Fundacionales
Gobernanza sobre Tooling
fireflayjs no compite por ejecutar builds más rápido.
Explora cómo hacer observables y gobernables:
- boundaries arquitectónicos
- contratos organizacionales
- relaciones estructurales
- coherencia ecosistémica
Autoridad Estructural, no de Implementación
fireflayjs gobierna:
- relaciones entre módulos
- contratos externos
- dependencias
- límites arquitectónicos
Cada módulo mantiene soberanía completa sobre su implementación interna.
Los equipos pueden utilizar:
- Vertical Slices
- Clean Architecture
- Layered Architecture
- patrones custom
todo dentro de su frontera arquitectónica.
Observabilidad antes que Restricción
La gobernanza arquitectónica primero:
- observa
- interpreta
- explica
- sugiere
- eventualmente restringe
El objetivo inicial no es castigar violations, sino generar visibilidad estructural continua y conciencia de sus implicancias.
Arquitectura como Metadata Ejecutable
La arquitectura no debería existir únicamente como diagramas o documentación estática.
Debería poder:
- declararse
- validarse
- analizarse
- visualizarse
- evolucionar
- integrarse al workflow de desarrollo
Complejidad Progresiva
El ecosistema busca permitir adopción incremental.
Un equipo podría comenzar utilizando únicamente:
- scaffolding estructural
- linting de boundaries
- análisis de dependencias
Y posteriormente explorar capacidades más avanzadas:
- contratos formales
- metadata de impacto
- observabilidad organizacional
- sincronización declarativa
- inteligencia ecosistémica
Contratos Arquitectónicos
La herramienta explora contratos arquitectónicos declarativos utilizando archivos TypeScript (ffjs.config.ts) para integrarse naturalmente con el ecosistema frontend moderno:
- tipado estricto
- autocompletado
- integración IDE
- validación de esquemas
- extensibilidad programática
Objetivo del Contrato
El contrato arquitectónico funciona como una descripción explícita del módulo y sus relaciones estructurales.
Puede modelar:
- ownership
- boundaries
- capacidades públicas
- intención de dependencia
- reglas de integración
- metadata organizacional
Ejemplo conceptual:
export default defineModule({
name: "user-authentication",
boundary: "feature",
exposes: ["LoginForm", "useAuthSession"],
consumes: {
react: "workspace",
"shared-ui": "workspace",
axios: "1.6.0",
},
});Dirección Evolutiva del Ecosistema
Las siguientes secciones describen posibles áreas de exploración futura del ecosistema.
No representan necesariamente features definitivas ni roadmap comprometido.
Fase 1 — Gobernanza, Contratos y Asistencia Contextual
Áreas Iniciales de Exploración
- estructura macro-arquitectónica
- boundary linting
- dependency graphing
- feedback arquitectónico contextual
- reconocimiento de patrones arquitectónicos
- asistencia en decisiones arquitectónicas en tiempo real
- metadata de impacto
Feedback Arquitectónico Contextual
Las violations arquitectónicas no deberían explicarse únicamente como reglas rotas.
El objetivo es producir feedback que:
- explique qué boundary se ve afectado
- contextualice por qué importa estructuralmente
- muestre posibles impactos organizacionales
- exponga trade-offs de la decisión tomada
- sugiera alternativas sin imponerlas
La intención es acercar el tooling a una experiencia de revisión arquitectónica continua y asistida.
Fase 2 — Metadata Ecosistémica
Posibles líneas evolutivas
- affected graph intelligence
- sincronización declarativa
- metadata para CI/CD
- análisis incremental de impacto
- coordinación entre módulos o tenants
Fase 3 — Observabilidad Arquitectónica
Posibles áreas futuras
- visualización de dependency graphs
- detección de architecture drift
- métricas de acoplamiento
- evolución de boundaries
- salud estructural del ecosistema
Adoption Playbooks
Migración Incremental
Uno de los principales objetivos del ecosistema es permitir adopción progresiva sobre sistemas existentes.
El objetivo no es reescribir plataformas completas, sino introducir gobernanza estructural de manera incremental.
Monolitos Legacy
Posible enfoque
- introducir módulos gobernados progresivamente
- declarar boundaries explícitos
- aislar nuevas features
- aplicar linting incrementalmente
Microfrontends Runtime
Posible dirección
- mover contratos implícitos de runtime hacia contratos explícitos de build-time
- mejorar observabilidad organizacional
- reducir acoplamiento invisible
Monorepos Existentes
fireflayjs busca coexistir con herramientas como:
- Nx
- Turborepo
- Lerna
sin reemplazar su responsabilidad principal como runners o sistemas de pipeline.
Visión de Largo Plazo
fireflayjs explora cómo transformar la arquitectura frontend en un sistema:
- declarativo
- observable
- ejecutable
- evolutivo
La dirección general del ecosistema gira alrededor de:
- contratos arquitectónicos
- observabilidad estructural
- inteligencia de impacto
- gobernanza organizacional
- evolución modular progresiva