Saltearse al contenido
Documentación de la Plataforma Algesta

Registros de Decisiones de Arquitectura (ADRs)

Introducción

Este documento contiene los Registros de Decisiones de Arquitectura (ADRs) para la Plataforma Algesta. Cada ADR captura una decisión arquitectónica importante tomada durante el proyecto, incluyendo el contexto, la decisión en sí, consecuencias, alternativas consideradas y justificación.

Los ADRs siguen el formato estándar:

  • Estado: Aceptado, Reemplazado o Deprecado
  • Contexto: El problema o asunto que se está abordando
  • Decisión: La elección arquitectónica tomada
  • Consecuencias: Resultados positivos y negativos
  • Alternativas Consideradas: Otras opciones evaluadas
  • Justificación: Por qué se tomó esta decisión
  • Fecha: Cuándo se tomó la decisión
  • Documentos Relacionados: Enlaces a documentación relevante

Tabla de Contenidos

ADR #TítuloEstadoFechaImpacto
ADR-001Microservicios NestJS sobre Azure FunctionsAceptado2024-Q2Alto
ADR-002MongoDB sobre CosmosDBAceptado2024-Q2Alto
ADR-003Redis/Kafka sobre Azure Event GridAceptado2024-Q2Alto
ADR-004React 19 sobre Flutter WebAceptado2024-Q2Alto
ADR-005Foto + OCR con IA sobre Códigos QR para Identificación de ActivosAceptado2024-Q3 (Sprint 6)Medio
ADR-006Cotización Basada en Items sobre Cotización GlobalAceptado2024-Q3 (Sprint 6)Alto
ADR-007Nuevo Historial de Activos sobre Integración con Sistema LegacyAceptado2024-Q3 (Sprint 6-7)Medio
ADR-008WhatsApp como Canal Primario sobre Aplicación Móvil NativaAceptado2024-Q1 (Sprint 1)Alto
ADR-009Patrón CQRS para Todos los MicroserviciosAceptado2024-Q2Medio
ADR-010Arquitectura Limpia con Diseño Guiado por el DominioAceptado2024-Q2Medio

ADR-001: Microservicios NestJS sobre Azure Functions

Estado: Aceptado

Contexto:

La plataforma Algesta requiere una arquitectura de backend para soportar:

  • Múltiples contextos delimitados (órdenes, proveedores, notificaciones)
  • Código base escalable y mantenible
  • Patrón CQRS para separación de comandos/consultas
  • Comunicación event-driven entre servicios
  • TypeScript para seguridad de tipos y experiencia de desarrollo

La propuesta inicial de arquitectura sugirió Azure Functions (serverless), pero el equipo necesitaba evaluar si esta era la mejor opción para los requisitos del proyecto.

Decisión:

Usar NestJS 11 con TypeScript para todos los microservicios de backend en lugar de Azure Functions.

Consecuencias:

Positivas:

  • Mejor Soporte TypeScript: NestJS es TypeScript-first con excelente inferencia de tipos
  • CQRS Integrado: El paquete @nestjs/cqrs proporciona CommandBus, QueryBus, EventBus listo para usar
  • Pruebas Más Fáciles: La inyección de dependencias hace las pruebas unitarias sencillas
  • Desarrollo Local: El stack completo de microservicios puede ejecutarse localmente sin emuladores de nube
  • Madurez del Framework: Gran ecosistema, comunidad activa, documentación extensa
  • Flexibilidad: No atado a Azure, se puede desplegar en cualquier plataforma de contenedores
  • Experiencia de Desarrollo: Hot reload, mejor depuración, base familiar de Express.js

Negativas:

  • Despliegue Más Complejo: Necesidad de gestionar contenedores vs. auto-escalamiento serverless
  • Mayor Costo Base: Contenedores siempre ejecutándose vs. pago por ejecución
  • Sobrecarga Operacional: Necesidad de gestionar orquestación de contenedores, health checks, escalamiento

Alternativas Consideradas:

  1. Azure Functions (Serverless)

    • Pros: Auto-escalamiento, pago por ejecución, cero mantenimiento
    • Contras: Cold starts, vendor lock-in, desarrollo local limitado, CQRS requiere implementación personalizada

  2. AWS Lambda con Node.js

    • Pros: Similar a Azure Functions, ecosistema maduro
    • Contras: Mismas limitaciones serverless, equipo menos familiarizado con AWS

  3. Spring Boot (Java)

    • Pros: Nivel empresarial, excelente soporte CQRS, tipado fuerte
    • Contras: Experiencia del equipo en TypeScript/JavaScript, mayor uso de recursos, arranque más lento

Justificación:

  • El equipo tiene fuerte experiencia en TypeScript/Node.js
  • CQRS es un requisito central, y NestJS lo proporciona listo para usar
  • Los patrones de Arquitectura Limpia son más fáciles de implementar con NestJS
  • Mejor experiencia de desarrollo conduce a mayor velocidad de desarrollo
  • La arquitectura de microservicios está bien soportada por NestJS
  • El despliegue en contenedores (Docker) proporciona flexibilidad y portabilidad

Fecha: 2024-Q2

Documentos Relacionados:

ADR-002: MongoDB sobre CosmosDB

Estado: Aceptado

Contexto:

La plataforma requiere una solución de base de datos para:

  • Esquema flexible (órdenes, proveedores, activos tienen estructuras variables)
  • Consultas complejas (filtros, agregaciones, búsqueda de texto completo)
  • Datos orientados a documentos (objetos anidados, arrays)
  • Solución costo-efectiva para fase de startup
  • Buena integración con NestJS/Mongoose

Azure Cosmos DB fue inicialmente considerado debido a la integración con el ecosistema Azure.

Decisión:

Usar MongoDB con Mongoose ODM en lugar de Azure Cosmos DB.

Consecuencias:

Positivas:

  • Menor Costo: MongoDB Atlas tier gratuito y menor costo a escala vs. pricing de RU de CosmosDB
  • Mejor Integración con Mongoose: Mongoose está diseñado para MongoDB, mejor validación de esquema
  • Lenguaje de Consulta Familiar: El lenguaje de consulta de MongoDB es bien conocido y documentado
  • Desarrollo Local Más Fácil: Se puede ejecutar MongoDB en Docker localmente
  • Hosting Flexible: Se puede usar MongoDB Atlas, auto-hospedado, o MongoDB hospedado en Azure

Negativas:

  • Menos Integración Nativa con Azure: No es un servicio de Azure de primera clase
  • Necesidad de Gestionar Hosting de MongoDB: Si es auto-hospedado, necesidad de gestionar backups, replicación, etc.
  • Sin Soporte Multi-Modelo: CosmosDB soporta grafos, clave-valor, familia de columnas

Alternativas Consideradas:

  1. Azure Cosmos DB (API MongoDB)

    • Pros: Nativo de Azure, distribución global, garantías SLA
    • Contras: Mayor costo (pricing basado en RU), vendor lock-in, modelo de pricing complejo

  2. PostgreSQL

    • Pros: Cumplimiento ACID, excelente para datos relacionales, soporte JSON
    • Contras: Esquema menos flexible, no ideal para documentos profundamente anidados

  3. DynamoDB

    • Pros: Serverless, nativo de AWS, baja latencia
    • Contras: Experiencia del equipo, vendor lock-in, patrones de consulta complejos

Justificación:

  • El costo es una preocupación mayor en fase de startup
  • El equipo tiene experiencia con MongoDB/Mongoose
  • El modelo de datos orientado a documentos se ajusta bien al dominio (órdenes con estructuras variables)
  • Mongoose proporciona excelente validación de esquema y seguridad de tipos con TypeScript
  • MongoDB Atlas proporciona hosting gestionado con buen tier gratuito

Fecha: 2024-Q2

Documentos Relacionados:

ADR-003: Redis/Kafka sobre Azure Event Grid

Estado: Aceptado

Contexto:

The Microservicios Arquitectura requires an event-driven communication mechanism for:

  • Asynchronous inter-service communication
  • Event sourcing and event history
  • Pub/sub pattern for notifications
  • Request/response pattern for queries
  • High throughput and low latency

Azure Event Grid was initially proposed due to Azure ecosystem alignment.

Decisión:

Use Redis or Apache Kafka for message broker instead of Azure Event Grid.

Consecuencias:

Positivas:

  • More Flexible: Redis/Kafka support multiple messaging patterns (pub/sub, request/response, streams)
  • Better NestJS Integration: @nestjs/Microservicios has first-class Redis/Kafka support
  • Easier Local Development: Can run Redis/Kafka in Docker locally
  • Open-Source: No vendor lock-in, can switch providers easily
  • Cost-Effective: Self-hosted or managed services at lower cost than Event Grid

Negativas:

  • Need to Manage Infrastructure: If self-hosting, need to manage broker cluster
  • Less Azure-Native: Not first-class Azure service
  • Operational Complexity: Need to monitor broker health, manage partitions/topics

Alternativas Consideradas:

  1. Azure Event Grid

    • Pros: Azure-native, serverless, pay-per-event
    • Cons: Limited messaging patterns, complex integration with NestJS, vendor lock-in

  2. Azure Service Bus

    • Pros: Azure-native, rich messaging Funcionalidades, good SLA
    • Cons: Higher cost, vendor lock-in, less NestJS support than Redis/Kafka

  3. RabbitMQ

    • Pros: Feature-rich, mature, good NestJS support
    • Cons: More complex than Redis, lower throughput than Kafka

Justificación:

  • NestJS Microservicios package has excellent Redis and Kafka transport Implementacións
  • Redis provides low-latency request/response and pub/sub
  • Kafka provides high-throughput event streaming (if needed for scale)
  • Flexibility to choose Redis for MVP and migrate to Kafka later if needed
  • Easy local development with Docker

Fecha: 2024-Q2

Documentos Relacionados:

ADR-004: React 19 sobre Flutter Web

Estado: Aceptado

Contexto:

The platform needs a frontend framework for:

  • Dashboard for Algesta team (order management, provider management, curation)
  • Provider portal (view auctions, submit offers, upload Documentos)
  • Client portal (view order Estado, approve quotations)
  • Responsive design for desktop and mobile browsers
  • Fast development velocity

Flutter Web was considered for cross-platform potential (web + mobile).

Decisión:

Use React 19 with TypeScript, Vite, and shadcn/ui instead of Flutter Web.

Consecuencias:

Positivas:

  • Larger Ecosystem: More libraries, more developers, more resources
  • Better Web Performance: React is optimized for web, Flutter Web is still maturing
  • Mature Tooling: Vite for fast build, excellent TypeScript support
  • Componente Libraries: shadcn/ui provides high-quality, accessible Componentes
  • Team Expertise: Team has React experience
  • Job Market: Easier to hire React developers

Negativas:

  • Not Cross-Platform Mobile: Cannot reuse code for native mobile apps (Flutter advantage)
  • Framework Churn: React ecosystem changes frequently

Alternativas Consideradas:

  1. Flutter Web

    • Pros: Cross-platform (web + mobile), single codebase, good UI Componentes
    • Cons: Larger bundle size, SEO challenges, less mature for web, team learning curve

  2. Vue.js 3

    • Pros: Simpler than React, good performance, excellent Documentoation
    • Cons: Smaller ecosystem, less team expertise

  3. Angular

    • Pros: Enterprise-grade, comprehensive framework, TypeScript-first
    • Cons: Steeper learning curve, more opinionated, larger bundle size

Justificación:

  • Platform is web-first (WhatsApp is primary mobile channel for clients)
  • React provides best web performance and developer experience
  • Bulletproof React Arquitectura provides scalable folder structure
  • TanStack Query handles server state caching elegantly
  • Zustand provides lightweight client state management
  • shadcn/ui Componentes are accessible, customizable, and modern

Fecha: 2024-Q2

Documentos Relacionados:

ADR-005: Foto + OCR con IA sobre Códigos QR para Identificación de Activos

Estado: Aceptado

Contexto:

The platform needs to identify assets (air conditioners, water pumps, etc.) when creating maintenance orders. Two main approaches were considered:

  1. Print and attach QR codes to all assets
  2. Take photo of existing asset serial plate and use OCR to extract serial number

The decision impacts operational costs, user experience, and accuracy.

Decisión:

Use photo capture + AI OCR (Tesseract.js) to read serial numbers from existing asset plates instead of QR code system.

Consecuencias:

Positivas:

  • No Operational Cost: No need to print/attach QR codes to thousands of assets
  • Works with Existing Assets: Can use existing serial plates, no asset modification needed
  • User-Friendly: Clients just take a photo (already familiar with WhatsApp photo capture)
  • Faster Despliegue: No physical asset tagging required

Negativas:

  • OCR Accuracy Challenges: Serial plates may be dirty, faded, or poorly lit
  • Requires User Confirmation: User must confirm extracted serial (adds friction)
  • AI Processing Time: OCR processing adds latency vs. instant QR scan
  • Fallback to Manual Entry: Need manual entry option when OCR fails

Alternativas Consideradas:

  1. QR Code System

    • Pros: 100% accurate, instant scan, no AI needed
    • Cons: High operational cost (print + attach to all assets), requires asset access

  2. Manual Serial Entry

    • Pros: Simple, no dependencies
    • Cons: Error-prone, slow, poor UX

  3. RFID Tags

    • Pros: No line-of-sight required, durable
    • Cons: Very high cost, requires special reader hardware

Justificación:

  • Algesta manages hundreds of assets across multiple client locations
  • Printing and attaching QR codes would require site visits to every asset
  • Most assets already have manufacturer serial plates
  • OCR accuracy is “good enough” with user confirmation step
  • Cost savings are significant (no printing, no site visits)
  • Can always add QR codes later for assets without readable serial plates

Fecha: 2024-Q3 (Sprint 6)

Documentos Relacionados:

ADR-006: Cotización Basada en Items sobre Cotización Global

Estado: Aceptado

Contexto:

The platform needs to manage quotations for maintenance orders. Two approaches were considered:

  1. Single global amount (provider quotes total, agent adds markup, client sees final price)
  2. Detailed item-based quotation (order broken into items, provider quotes per item, agent adjusts, client sees itemized breakdown)

The decision impacts transparency, accounting, and user experience.

Decisión:

Implement detailed item-based quotation (order → items → provider quotes per item → agent adjusts → client approves itemized quotation).

Consecuencias:

Positivas:

  • Better Traceability: Can track costs per item, identify expensive items
  • Client Transparency: Client sees exactly what they’re paying for
  • Accounting Accuracy: Detailed cost breakdown for financial reporting
  • Audit Trail: Clear history of what was quoted and approved
  • Change Management: Easy to adjust individual items if scope changes

Negativas:

  • More Complex UI/UX: Need to display tables of items, more clicks
  • Longer Quotation Process: Agent must break down order, provider must quote each item
  • More Data to Manage: Store and validate multiple items instead of one amount

Alternativas Consideradas:

  1. Single Global Quotation

    • Pros: Simpler UX, faster quotation process, less data
    • Cons: No transparency, harder to justify costs, poor accounting detail

  2. Category-Based Quotation

    • Pros: Middle ground between global and item-based
    • Cons: Still lacks detail, harder to implement than either extreme

Justificación:

  • Client Requisito: Clients (especially enterprise) demand cost transparency
  • Accounting Requisito: Finance team needs detailed cost breakdown for budgeting
  • Regulatory compliance: Some industries require itemized invoices
  • Competitive advantage: Transparency builds trust with clients
  • Change management: Clients often request scope changes, itemized quotation makes this easier

Fecha: 2024-Q3 (Sprint 6, Sprint 8)

Documentos Relacionados:

ADR-007: Nuevo Historial de Activos sobre Integración con Sistema Legacy

Estado: Aceptado

Contexto:

Algesta has a legacy asset management system with 500+ fields per asset. The platform needs to track asset history (Hoja de Vida) for maintenance orders. Two approaches were considered:

  1. Full integration with legacy system (complex, comprehensive)
  2. Build new lightweight Asset History (simple, focused on essential data)

The decision impacts development timeline, data duplication, and feature Completoness.

Decisión:

Build new lightweight Asset History (Hoja de Vida) focused on maintenance events instead of full integration with legacy system.

Consecuencias:

Positivas:

  • Simpler Data Model: Only 20-30 essential fields vs. 500+ in legacy system
  • Faster Development: No complex ETL, API integration, or data mapping
  • Easier Maintenance: Own the schema, can evolve independently
  • Focused on Use Case: Optimized for maintenance history, not general asset management
  • Better UX: Clean interface without legacy system’s complexity

Negativas:

  • Data Duplication: Some asset data duplicated between systems
  • Need Migration Strategy: Eventually need to sync or migrate data
  • No Access to Legacy History: Old maintenance records not in new system
  • Two Sources of Truth: Risk of data inconsistency

Alternativas Consideradas:

  1. Full Integration with Legacy System

    • Pros: Single source of truth, access to historical data, no duplication
    • Cons: Complex integration, 500+ fields overwhelming, slow development, tight coupling

  2. Hybrid Approach (Read from legacy, write to new)

    • Pros: Access to legacy data, new data in new system
    • Cons: Complex sync logic, eventual consistency challenges

Justificación:

  • Legacy system has 500+ fields, most irrelevant for maintenance workflow
  • MVP timeline requires focused scope
  • Asset history for maintenance is a distinct bounded context
  • Can build integration later if business Valor justifies complexity
  • Simpler system enables faster iteration and UX improvements

Fecha: 2024-Q3 (Sprint 6-7)

Documentos Relacionados:

ADR-008: WhatsApp como Canal Primario sobre Aplicación Móvil Nativa

Estado: Aceptado

Contexto:

Clients need a way to create orders, view Estado, and approve quotations. Two approaches were considered:

  1. Native mobile app (iOS + Android)
  2. WhatsApp bot via Jelou platform

The decision impacts development cost, user adoption, and feature richness.

Decisión:

Use WhatsApp via Jelou bot as primary channel for client interaction instead of building native mobile app.

Consecuencias:

Positivas:

  • No App Installation Required: Clients already have WhatsApp installed
  • Familiar Interface: Users know how to use WhatsApp
  • Lower Development Cost: No need to build iOS + Android apps
  • Faster Time to Market: Jelou bot can be configured in weeks vs. months for apps
  • High Adoption: WhatsApp has 95%+ penetration in target market (Latin America)
  • Push Notifications Built-In: WhatsApp messages are push notifications

Negativas:

  • Dependency on Meta/WhatsApp: Subject to platform policies and changes
  • Limited UI Customization: Constrained by WhatsApp interface (text, buttons, lists)
  • Approval Process Risks: WhatsApp Business API requires approval
  • Feature Limitations: Complex UIs (multi-step forms, rich tables) are challenging

Alternativas Consideradas:

  1. Native Mobile App (iOS/Android)

    • Pros: Full UI control, rich Funcionalidades, offline support
    • Cons: High development cost, app store approval, user installation friction

  2. Progressive Web App (PWA)

    • Pros: Cross-platform, no app store, easier than native
    • Cons: Still requires user to find and bookmark, less familiar than WhatsApp

  3. SMS

    • Pros: No smartphone required, universal
    • Cons: No rich media, high cost per message, poor UX

Justificación:

  • Target market (Latin America) has extremely high WhatsApp usage
  • Clients prefer messaging over app downloads
  • MVP can launch faster with WhatsApp bot
  • Development cost savings can be invested in core Funcionalidades
  • Can always add mobile app later if WhatsApp limitations become problematic

Fecha: 2024-Q1 (Sprint 1)

Documentos Relacionados:

ADR-009: Patrón CQRS para Todos los Microservicios

Estado: Aceptado

Contexto:

The Microservicios need a pattern for handling business logic. Traditional CRUD vs. CQRS was evaluated.

Decisión:

Implement CQRS (Command Query Responsibility Segregation) pattern in all Microservicios.

Consecuencias:

Positivas:

  • Clear Separation of Concerns: Commands (write) and queries (read) are separate
  • Better Scalability: Can optimize read and write models independently
  • Easier Pruebas: Commands and queries can be tested in isolation
  • Audit Trail: Commands naturally create event history
  • Domain-Driven Design: Aligns well with DDD principles

Negativas:

  • More Boilerplate Code: Need separate handlers for commands and queries
  • Learning Curve: Team needs to understand CQRS concepts
  • Increased Complexity: More files, more abstraction layers

Alternativas Consideradas:

  1. Traditional CRUD

    • Pros: Simple, less code, familiar pattern
    • Cons: Read and write logic mixed, harder to scale, less clean

  2. Event Sourcing + CQRS

    • Pros: Completo audit trail, time travel, ultimate scalability
    • Cons: Very complex, requires event store, steep learning curve

Justificación:

  • NestJS has first-class CQRS support via @nestjs/cqrs
  • Aligns with Clean Architecture principles
  • Business logic is complex enough to benefit from separation
  • Future scalability: can split read/write databases if needed

Fecha: 2024-Q2

Documentos Relacionados:

  • Componente diagrams for all Microservicios

ADR-010: Arquitectura Limpia con Diseño Guiado por el Dominio

Estado: Aceptado

Contexto:

The Microservicios need a code organization pattern for long-term maintainability.

Decisión:

Implement Clean Architecture with DDD principles (Domain, Application, Infrastructure layers).

Consecuencias:

Positivas:

  • Testability: Domain logic has no framework dependencies, easy to unit test
  • Maintainability: Clear boundaries between layers
  • Tecnología Independence: Can swap infrastructure (Base de datos, messaging) without changing domain
  • Team Scalability: Multiple developers can work on different layers

Negativas:

  • More Initial Setup: More folders, more abstraction
  • Steeper Learning Curve: Team needs to understand Clean Architecture
  • More Files: Each feature has multiple files across layers

Alternativas Consideradas:

  1. MVC Pattern

    • Pros: Simple, familiar, less abstraction
    • Cons: Business logic mixed with controllers, harder to test

  2. Layered Arquitectura

    • Pros: Clear layers, better than MVC
    • Cons: Dependency flows downward, domain depends on infrastructure

Justificación:

  • Long-term maintainability is critical
  • Team will scale, need clear Arquitectura
  • Domain logic is complex (auctions, quotations, lifecycle management)
  • Aligns with CQRS and DDD principles

Fecha: 2024-Q2

Documentos Relacionados:

Tabla Resumen

ADR #TítuloTecnología ElegidaAlternativaImpactoMotor de Negocio
ADR-001Framework BackendNestJS 11Azure FunctionsAltoExperiencia del desarrollador, soporte CQRS
ADR-002Base de DatosMongoDBCosmosDBAltoCosto, flexibilidad
ADR-003Message BrokerRedis/KafkaAzure Event GridAltoIntegración con NestJS, costo
ADR-004Framework FrontendReact 19Flutter WebAltoRendimiento web, ecosistema
ADR-005Identificación de ActivosFoto + OCRCódigos QRMedioAhorro en costos operacionales
ADR-006Modelo de CotizaciónBasado en ItemsMonto GlobalAltoTransparencia con cliente, contabilidad
ADR-007Historial de ActivosNuevo SistemaIntegración LegacyMedioVelocidad de desarrollo, simplicidad
ADR-008Canal de ClienteWhatsAppApp NativaAltoAdopción de usuario, costo de desarrollo
ADR-009Patrón de CódigoCQRSCRUD TradicionalMedioEscalabilidad, mantenibilidad
ADR-010ArquitecturaArquitectura LimpiaMVCMedioMantenibilidad a largo plazo

Referencias Cruzadas

  • Documentación de Sprints: Ver docs/Sprint_1.md hasta Sprint_8.md en el repositorio del proyecto
  • Análisis de Backlog: Ver docs/complete_backlog_analysis.md en el repositorio del proyecto
  • Documentación de Arquitectura: Ver barra lateral de navegación para todos los documentos de arquitectura
  • Detalles de Implementación: Diagramas de componentes y diagramas de flujo de datos