workspace "HERO Platform" "Plataforma de Atención Domiciliaria" {

    model {
        # Personas (Actors)
        medico = person "Médico/Profesional" "Realiza visitas domiciliarias, gestiona agenda y rutas"
        paciente = person "Paciente" "Recibe atención médica domiciliaria"
        admin = person "Administrador" "Gestiona instituciones, sedes, catálogos y usuarios"

        # Sistema Principal
        hero = softwareSystem "HERO Platform" "Plataforma de gestión de atención domiciliaria con optimización de rutas" {

            # Frontend Container
            flutterWeb = container "Flutter Web/Mobile" "Aplicación web y móvil" "Flutter 3.6+, Dart" {
                description "Interfaz de usuario responsive con Mason bricks para generación de código, Lefthook para Git hooks. Referencia: hero-flutter/README.md"
                tags "Web Browser"
            }

            # API Gateway Container
            apiGateway = container "API Gateway" "Punto de entrada único, enrutamiento y autenticación centralizada" "NestJS 11+, TypeScript, CQRS" {
                description "Implementa patrón Gateway con Clean Architecture + CQRS, interceptores globales (ResponseInterceptor), guards JWT, comunicación Redis con microservicios. Puerto: 3000. Referencia: api-gateway/README.md, api-gateway/docs/API-Gateway-Hero.md"
                tags "API"

                # API Gateway Components (C3)
                authController = component "AuthController" "Endpoints de autenticación" "NestJS Controller" {
                    description "Métodos: register, login, loginDni, loginDev, verifyEmail, verifyLogin, resetPassword, updatePassword, logout, updateSpecialty. Referencia: api-gateway/src/infrastructure/controllers/auth.controller.ts"
                }

                patientController = component "PatientController" "Endpoints de pacientes" "NestJS Controller" {
                    description "Métodos: create, getAll, getById, update, delete. Interceptores: PatientTypeResponseInterceptor, InsuranceTypeResponseInterceptor. Referencia: api-gateway/src/infrastructure/controllers/patient.controller.ts"
                }

                routeController = component "RouteController" "Endpoints de rutas" "NestJS Controller" {
                    description "Métodos: create, getAll, getById, update, delete. Referencia: api-gateway/src/infrastructure/controllers/route.controller.ts"
                }

                commandBus = component "CommandBus" "Bus de comandos CQRS" "@nestjs/cqrs" {
                    description "Ejecuta comandos de escritura (CreatePatientCommand, UpdateRouteCommand, etc.)"
                }

                queryBus = component "QueryBus" "Bus de consultas CQRS" "@nestjs/cqrs" {
                    description "Ejecuta queries de lectura (GetPatientByIdQuery, GetAllRoutesQuery, etc.)"
                }

                jwtAuthGuard = component "JwtAuthGuard" "Guard de autenticación JWT" "NestJS Guard" {
                    description "Valida tokens JWT en headers Authorization, inyecta user context. Referencia: api-gateway/src/shared/guards/jwt-auth.guard.ts"
                }

                responseInterceptor = component "ResponseInterceptor" "Interceptor de respuestas" "NestJS Interceptor" {
                    description "Estandariza respuestas con statusCode, message, timestamp, traceId. Referencia: api-gateway/src/infrastructure/rest/interceptors/response.interceptor.ts"
                }

                redisService = component "RedisService" "Cliente Redis" "MessagingStrategy" {
                    description "Comunicación RPC con microservicios, timeout 120s, retry 2. Referencia: api-gateway/src/infrastructure/messaging/redis.service.ts"
                }

                loginHandler = component "LoginHandler" "Handler de login" "CommandHandler"
                createPatientHandler = component "CreatePatientHandler" "Handler de creación de paciente" "CommandHandler"
                getPatientByIdHandler = component "GetPatientByIdHandler" "Handler de consulta de paciente" "QueryHandler"
            }

            # Microservices Containers
            msAuth = container "ms-auth" "Autenticación, autorización, gestión de usuarios" "NestJS, TypeORM, PostgreSQL" {
                description "JWT con access tokens (24h) y refresh tokens (7d), MFA por email (códigos 6 dígitos, 10 min), bcrypt rounds=12. Puerto: 3002. Schema: ms_auth. Referencia: ms-auth/README.md (sección Security)"
                tags "Microservice"

                # ms-auth Components (C3)
                authRpcController = component "AuthRpcController" "Controlador RPC" "NestJS MessagePattern" {
                    description "Patterns: auth.register, auth.login, auth.verify-email, auth.verify-login, auth.reset-password, auth.logout. Referencia: ms-auth/src/infrastructure/controllers/"
                }

                jwtStrategy = component "JwtStrategy" "Estrategia JWT" "Passport Strategy" {
                    description "Valida tokens JWT, extrae payload"
                }

                loginHandlerAuth = component "LoginHandler" "Handler de login" "CommandHandler" {
                    description "Valida credenciales, genera access token (24h) y refresh token (7d), envía código MFA por email. Referencia: ms-auth/src/application/handlers/commands/auth/login.handler.ts"
                }

                verifyEmailHandler = component "VerifyEmailHandler" "Handler de verificación email" "CommandHandler" {
                    description "Valida código de 6 dígitos (10 min expiration), marca email como verificado. Referencia: ms-auth/README.md (handlers de verificación)"
                }

                userRepository = component "UserRepository" "Repositorio de usuarios" "TypeORM Repository" {
                    description "Tabla: users (id, email, password, firstName, lastName, documentType, documentNumber, specialty, isEmailVerified). Referencia: ms-auth/README.md (schema de base de datos)"
                }

                refreshTokenRepository = component "RefreshTokenRepository" "Repositorio de refresh tokens" "TypeORM Repository" {
                    description "Tabla: refresh_tokens (id, userId, token, expiresAt, createdAt). TTL 7 días. Referencia: ms-auth/README.md (schema de base de datos)"
                }

                emailVerificationRepository = component "EmailVerificationRepository" "Repositorio de verificación de email" "TypeORM Repository" {
                    description "Tabla: email_verifications (id, userId, code, expiresAt, isVerified, createdAt). Códigos MFA de 6 dígitos con expiración 10 min. Referencia: ms-auth/README.md (schema de base de datos)"
                }

                emailService = component "EmailService" "Servicio de emails" "SendGrid Client" {
                    description "Envía emails de verificación, reset password, bienvenida. Templates: SENDGRID_VERIFICATION_CODE, SENDGRID_VERIFY_EMAIL, SENDGRID_RESET_PASSWORD"
                }
            }

            msPatient = container "ms-patient" "Gestión de pacientes" "NestJS, TypeORM, PostgreSQL" {
                description "CRUD pacientes, generación automática de número de caso, clasificación de riesgo, búsqueda avanzada. Puerto: 3003. Schema: ms_patient. Referencia: hero-ms-patient-nestjs/README.md"
                tags "Microservice"

                # ms-patient Components (C3)
                patientRpcController = component "PatientController" "Controlador RPC de pacientes" "NestJS MessagePattern" {
                    description "Patterns: patient.create, patient.findAll, patient.findById, patient.update, patient.delete, patient.search. Referencia: hero-ms-patient-nestjs/src/infrastructure/controllers/patient.controller.ts"
                }

                msPatientCreatePatientHandler = component "CreatePatientHandler" "Handler de creación de paciente" "CommandHandler" {
                    description "Genera número de caso automático (CASE-YYYY-NNNNNN), clasifica riesgo (HIGH/MEDIUM/LOW), valida unicidad de documento"
                }

                caseNumberGenerator = component "CaseNumberGenerator" "Generador de número de caso" "Service" {
                    description "Formato: CASE-YYYY-NNNNNN, secuencia autoincremental, validación de unicidad"
                }

                riskClassifier = component "RiskClassifier" "Clasificador de riesgo" "Service" {
                    description "Clasifica pacientes en HIGH/MEDIUM/LOW basado en condiciones"
                }

                patientRepository = component "PatientRepository" "Repositorio de pacientes" "TypeORM Repository" {
                    description "Tabla: patients con enums (RiskLevel, LegalStatus, AgeGroup, ServiceTypes)"
                }
            }

            msPractitioner = container "ms-practitioner" "Gestión de profesionales y agenda" "NestJS, TypeORM, PostgreSQL" {
                description "CRUD profesionales, gestión de agenda con slots y bloques de disponibilidad. Schema: ms_practitioner. Referencia: hero-ms-practitioner-nestjs/README.md"
                tags "Microservice"

                # ms-practitioner Components (C3)
                practitionerRpcController = component "PractitionerController" "Controlador RPC de profesionales" "NestJS MessagePattern" {
                    description "Patterns: practitioner.create, practitioner.findAll. Referencia: hero-ms-practitioner-nestjs/src/infrastructure/controllers/practitioner.controller.ts"
                }

                specialtyRpcController = component "SpecialtyController" "Controlador RPC de especialidades" "NestJS MessagePattern" {
                    description "Patterns: specialty.findAll. Referencia: hero-ms-practitioner-nestjs/src/infrastructure/controllers/specialty.controller.ts"
                }

                vehicleRpcController = component "VehicleController" "Controlador RPC de vehículos" "NestJS MessagePattern" {
                    description "Patterns: vehicle.findAll. Referencia: hero-ms-practitioner-nestjs/src/infrastructure/controllers/vehicle.controller.ts"
                }

                agendaSlotRpcController = component "AgendaSlotController" "Controlador RPC de slots" "NestJS MessagePattern" {
                    description "Patterns: agenda-slot.create, agenda-slot.getNetAvailability, agenda-slot.getNetAvailabilityBySpecialty, agenda-slot.update, agenda-slot.delete"
                }

                agendaBlockRpcController = component "AgendaBlockController" "Controlador RPC de bloques" "NestJS MessagePattern" {
                    description "Patterns: agenda-block.create, agenda-block.findAllByPractitionerId, agenda-block.getAvailablePractitioners, agenda-block.update, agenda-block.delete"
                }

                createPractitionerHandler = component "CreatePractitionerHandler" "Handler de creación de profesional" "CommandHandler" {
                    description "Crea profesional con especialidad, vehículo, zonas de trabajo"
                }

                getNetAvailabilityHandler = component "GetNetAvailabilityHandler" "Handler de disponibilidad neta" "QueryHandler" {
                    description "Calcula disponibilidad neta considerando bloques y slots"
                }

                workAreaManager = component "WorkAreaManager" "Gestor de zonas de trabajo" "Service" {
                    description "Gestiona zonas de trabajo asignadas a profesionales"
                }

                availabilityCalculator = component "AvailabilityCalculator" "Calculador de disponibilidad" "Service" {
                    description "Calcula disponibilidad neta (slots - bloques ocupados)"
                }

                practitionerRepository = component "PractitionerRepository" "Repositorio de profesionales" "TypeORM Repository" {
                    description "Tabla: practitioners"
                }

                specialtyRepository = component "SpecialtyRepository" "Repositorio de especialidades" "TypeORM Repository" {
                    description "Tabla: specialties"
                }

                vehicleRepository = component "VehicleRepository" "Repositorio de vehículos" "TypeORM Repository" {
                    description "Tabla: vehicles"
                }

                agendaSlotRepository = component "AgendaSlotRepository" "Repositorio de slots" "TypeORM Repository" {
                    description "Tabla: agenda_slots"
                }

                agendaBlockRepository = component "AgendaBlockRepository" "Repositorio de bloques" "TypeORM Repository" {
                    description "Tabla: agenda_blocks"
                }
            }

            msRoute = container "hero-ms-route-nestjs" "Optimización de rutas" "NestJS, TypeORM, PostgreSQL, Google Routes API" {
                description "Optimización TSP greedy con prioridades (alta/media/baja), lockOrder, ventanas de tiempo, cálculo CO2. Schema: ms_route. Referencia: hero-ms-route-nestjs/README.md, DOCUMENTACION_OPTIMIZACION_RUTAS.md"
                tags "Microservice"

                # hero-ms-route-nestjs Components (C3)
                routeRpcController = component "RouteRpcController" "Controlador RPC" "NestJS MessagePattern" {
                    description "Patterns: route.create, route.update, route.getAll, route.getById, route.delete"
                }

                visitRpcController = component "VisitController" "Controlador RPC de visitas" "NestJS MessagePattern" {
                    description "Patterns: visit.create, visit.findAll, visit.findById, visit.update, visit.delete, visit.search, visit.findByPractitionerAndInterval. Referencia: hero-ms-route-nestjs/src/infrastructure/controllers/visit.controller.ts"
                }

                createRouteHandler = component "CreateRouteHandler" "Handler de creación de ruta" "CommandHandler" {
                    description "Geocodifica direcciones, optimiza ruta con RouteOptimizerService, calcula métricas (distancia, tiempo, CO2). Referencia: hero-ms-route-nestjs/DOCUMENTACION_OPTIMIZACION_RUTAS.md (CreateRouteHandler)"
                }

                createVisitHandler = component "CreateVisitHandler" "Handler de creación de visita" "CommandHandler" {
                    description "Crea visita con dirección, prioridad, lockOrder y duración"
                }

                getVisitsHandler = component "GetVisitsHandler" "Handler de consulta de visitas" "QueryHandler" {
                    description "Consulta visitas con filtros (routeId, practitionerId, fechas)"
                }

                routeOptimizerService = component "RouteOptimizerService" "Servicio de optimización" "Service" {
                    description "Algoritmo TSP greedy, separa puntos por prioridad (alta/media/baja), respeta lockOrder, considera ventanas de tiempo. Referencia: DOCUMENTACION_OPTIMIZACION_RUTAS.md (RouteOptimizerService)"
                }

                googleRoutesService = component "GoogleRoutesService" "Cliente Google Routes API" "HttpService" {
                    description "Métodos: computeRouteMatrix, computeRoutes, geocodeAddress, reverseGeocode. GAP: Sin timeouts ni reintentos. Referencia: hero-ms-route-nestjs/src/shared/services/google-routes.service.ts"
                }

                circuitBreakerService = component "CircuitBreakerService" "Circuit Breaker" "Service" {
                    description "Estados CLOSED/OPEN/HALF_OPEN, threshold 5 fallos, recovery timeout 60s. Referencia: hero-ms-route-nestjs/src/shared/services/circuit-breaker.service.ts"
                }

                routeRepository = component "RouteRepository" "Repositorio de rutas" "TypeORM Repository" {
                    description "Tabla: routes (id, practitionerId, code, startDate, endDate, status, startAddress, endAddress, vehiclePlate, totalVisits, totalDurationMinutes, totalDistanceKm, co2eq, calculatedRoute, isActive)"
                }

                visitRepository = component "VisitRepository" "Repositorio de visitas" "TypeORM Repository" {
                    description "Tabla: visits (id, patientId, practitionerId, routeId, stimatedStartDate, stimatedEndDate, status, priority, mainAddress, latitude, longitude, plannedOrder, lockOrder, durationMinutes)"
                }
            }

            msEncounter = container "ms-encounter" "Gestión de ingresos/encuentros" "NestJS, TypeORM, PostgreSQL" {
                description "CRUD encuentros médicos, relación con pacientes y profesionales. Schema: ms_encounter"
                tags "Microservice"

                # ms-encounter Components (C3)
                encounterRpcController = component "EncounterController" "Controlador RPC de encuentros" "NestJS MessagePattern" {
                    description "Patterns: encounter.create, encounter.findAll, encounter.findById, encounter.findByPatientId, encounter.update, encounter.delete, encounter.search. Referencia: hero-ms-encounter-nestjs/src/infrastructure/controllers/encounter.controller.ts"
                }

                procedureRpcController = component "ProcedureController" "Controlador RPC de procedimientos" "NestJS MessagePattern" {
                    description "Patterns: procedure.create, procedure.findAll, procedure.findById, procedure.findByEncounterId, procedure.update, procedure.delete"
                }

                medicationRequestRpcController = component "MedicationRequestController" "Controlador RPC de medicamentos" "NestJS MessagePattern" {
                    description "Patterns: medication-request.create, medication-request.findAll, medication-request.findById, medication-request.findByEncounterId, medication-request.update, medication-request.delete"
                }

                createEncounterHandler = component "CreateEncounterHandler" "Handler de creación de encuentro" "CommandHandler" {
                    description "Crea encuentro médico con relación a paciente y profesional"
                }

                createProcedureHandler = component "CreateProcedureHandler" "Handler de creación de procedimiento" "CommandHandler" {
                    description "Crea procedimiento asociado a encuentro"
                }

                procedureManager = component "ProcedureManager" "Gestor de procedimientos" "Service" {
                    description "Gestiona procedimientos por encuentro, valida catálogo maestro"
                }

                medicationValidator = component "MedicationValidator" "Validador de medicamentos" "Service" {
                    description "Valida medicamentos contra catálogo maestro, valida dosis"
                }

                encounterRepository = component "EncounterRepository" "Repositorio de encuentros" "TypeORM Repository" {
                    description "Tabla: encounters"
                }

                procedureRepository = component "ProcedureRepository" "Repositorio de procedimientos" "TypeORM Repository" {
                    description "Tabla: procedures"
                }

                medicationRepository = component "MedicationRepository" "Repositorio de medicamentos" "TypeORM Repository" {
                    description "Tabla: medication_requests"
                }
            }

            msInstitutions = container "ms-institutions" "Gestión de instituciones y sedes" "NestJS, TypeORM, PostgreSQL" {
                description "CRUD instituciones, sedes (headquarters), zonas geográficas. Schema: ms_institution"
                tags "Microservice"

                # ms-institutions Components (C3)
                institutionRpcController = component "InstitutionController" "Controlador RPC de instituciones" "NestJS MessagePattern" {
                    description "Patterns: institution.create, institution.getProfile. Referencia: hero-ms-institutions-nestjs/src/infrastructure/controllers/institution.controller.ts"
                }

                headquarterRpcController = component "HeadquarterController" "Controlador RPC de sedes" "NestJS MessagePattern" {
                    description "Patterns: headquarter.create, headquarter.findAllByInstitution, headquarter.findById"
                }

                zoneRpcController = component "ZoneController" "Controlador RPC de zonas" "NestJS MessagePattern" {
                    description "Patterns: zone.create, zone.findAllByHeadquarter, zone.findByCoordinates"
                }

                createInstitutionHandler = component "CreateInstitutionHandler" "Handler de creación de institución" "CommandHandler" {
                    description "Crea institución de salud"
                }

                findZoneByCoordinatesHandler = component "FindZoneByCoordinatesHandler" "Handler de búsqueda de zona" "QueryHandler" {
                    description "Busca zona por coordenadas (lat/lng)"
                }

                zoneManager = component "ZoneManager" "Gestor de zonas geográficas" "Service" {
                    description "Gestiona zonas geográficas por sede, valida polígonos"
                }

                headquarterValidator = component "HeadquarterValidator" "Validador de sedes" "Service" {
                    description "Valida que sedes tengan datos completos"
                }

                institutionRepository = component "InstitutionRepository" "Repositorio de instituciones" "TypeORM Repository" {
                    description "Tabla: institutions"
                }

                headquarterRepository = component "HeadquarterRepository" "Repositorio de sedes" "TypeORM Repository" {
                    description "Tabla: headquarters"
                }

                zoneRepository = component "ZoneRepository" "Repositorio de zonas" "TypeORM Repository" {
                    description "Tabla: zones (con coordenadas geográficas)"
                }
            }

            msCatalogs = container "ms-catalogs" "Catálogos dinámicos" "NestJS, TypeORM, PostgreSQL" {
                description "Gestión de catálogos configurables (países, ciudades, especialidades, etc.). Schema: ms_catalog"
                tags "Microservice"

                # ms-catalogs Components (C3)
                catalogRpcController = component "CatalogController" "Controlador RPC de catálogos" "NestJS MessagePattern" {
                    description "Múltiples patterns CRUD para catálogos estáticos. Referencia: hero-ms-catalogs-nestjs/src/infrastructure/controllers/catalog.controller.ts"
                }

                dynamicCatalogRpcController = component "DynamicCatalogController" "Controlador RPC de catálogos dinámicos" "NestJS MessagePattern" {
                    description "12+ patterns para definitions e items (createDefinition, createItem, getCatalogByCode, etc.)"
                }

                countryRpcController = component "CountryController" "Controlador RPC de países" "NestJS MessagePattern" {
                    description "Patterns: country.create, country.findAll, country.findById, country.update, country.delete"
                }

                stateRpcController = component "StateController" "Controlador RPC de estados" "NestJS MessagePattern" {
                    description "Patterns: state.create, state.findAll por countryId, state.findById, state.update, state.delete, state.findAllState"
                }

                cityRpcController = component "CityController" "Controlador RPC de ciudades" "NestJS MessagePattern" {
                    description "Patterns: city.create, city.findAll por stateId, city.findById, city.update, city.delete, city.findAllCity"
                }

                createDefinitionHandler = component "CreateDefinitionHandler" "Handler de creación de definición" "CommandHandler" {
                    description "Crea definición de catálogo dinámico (configurable)"
                }

                getCatalogByCodeHandler = component "GetCatalogByCodeHandler" "Handler de obtención de catálogo" "QueryHandler" {
                    description "Obtiene catálogo completo por código"
                }

                catalogManager = component "CatalogManager" "Gestor de catálogos" "Service" {
                    description "Gestiona catálogos dinámicos, valida definiciones"
                }

                hierarchyValidator = component "HierarchyValidator" "Validador de jerarquías" "Service" {
                    description "Valida jerarquías geográficas (país → estado → ciudad)"
                }

                catalogRepository = component "CatalogRepository" "Repositorio de catálogos" "TypeORM Repository" {
                    description "Tabla: catalogs"
                }

                dynamicCatalogRepository = component "DynamicCatalogRepository" "Repositorio de catálogos dinámicos" "TypeORM Repository" {
                    description "Tablas: definitions, items"
                }

                countryRepository = component "CountryRepository" "Repositorio de países" "TypeORM Repository" {
                    description "Tabla: countries"
                }

                stateRepository = component "StateRepository" "Repositorio de estados" "TypeORM Repository" {
                    description "Tabla: states"
                }

                cityRepository = component "CityRepository" "Repositorio de ciudades" "TypeORM Repository" {
                    description "Tabla: cities"
                }
            }

            # Data Layer Containers
            postgresql = container "PostgreSQL" "Base de datos relacional multi-tenant" "PostgreSQL 15" {
                description "Schemas aislados por microservicio y tenant (ms_auth, ms_patient, ms_route, etc.), SSL habilitado, pool max=20. Referencia: hero-ops/infrastructure/tenants/sample/main.tf (configuración PostgreSQL)"
                tags "Database"
            }

            redis = container "Redis" "Caché y messaging inter-servicios" "Redis 5+" {
                description "Refresh tokens, comunicación RPC entre API Gateway y microservicios, timeout 120s, retry 2. Referencia: api-gateway/src/infrastructure/messaging/redis.service.ts (configuración Redis)"
                tags "Cache/Message Broker"
            }

            # Infrastructure Containers
            gke = container "GKE Cluster" "Orquestación de contenedores" "Google Kubernetes Engine" {
                description "Cluster privado con node pools spot, HPA, namespaces por environment (prod, qa, staging). Referencia: hero-ops/infrastructure/tenants/sample/main.tf (módulo GKE)"
                tags "Infrastructure"
            }

            firebaseHosting = container "Firebase Hosting" "Hosting frontend" "Firebase" {
                description "CDN global para Flutter web, custom domains. Referencia: hero-ops/infrastructure/tenants/sample/main.tf (módulo Firebase)"
                tags "Infrastructure"
            }
        }

        # External Systems
        googleRoutes = softwareSystem "Google Routes API" "Optimización de rutas, geocoding y cálculo de distancias" {
            tags "External"
        }
        googleMaps = softwareSystem "Google Maps API" "Visualización de mapas y geocoding" {
            tags "External"
        }
        sendgrid = softwareSystem "SendGrid" "Envío de emails transaccionales (verificación, reset password)" {
            tags "External"
        }
        firebase = softwareSystem "Firebase Hosting" "Hosting de aplicación Flutter web" {
            tags "External"
        }

        # C1 Relationships (Context Level)
        medico -> hero "Gestiona agenda, visitas y rutas"
        paciente -> hero "Consulta información de atención"
        admin -> hero "Administra plataforma"
        hero -> googleRoutes "Optimiza rutas y geocodifica direcciones"
        hero -> googleMaps "Visualiza mapas"
        hero -> sendgrid "Envía emails"
        hero -> firebase "Despliega frontend"

        # C2 Relationships (Container Level)
        flutterWeb -> apiGateway "Consume API REST" "HTTPS/JSON"
        apiGateway -> msAuth "Autentica usuarios" "Redis RPC"
        apiGateway -> msPatient "Gestiona pacientes" "Redis RPC"
        apiGateway -> msPractitioner "Gestiona profesionales" "Redis RPC"
        apiGateway -> msRoute "Optimiza rutas" "Redis RPC"
        apiGateway -> msEncounter "Gestiona encuentros" "Redis RPC"
        apiGateway -> msInstitutions "Gestiona instituciones" "Redis RPC"
        apiGateway -> msCatalogs "Consulta catálogos" "Redis RPC"
        apiGateway -> redis "Comunica con MS" "Redis Protocol"

        msAuth -> postgresql "Lee/escribe datos" "SQL/SSL"
        msAuth -> redis "Recibe mensajes" "Redis Protocol"
        msPatient -> postgresql "Lee/escribe datos" "SQL/SSL"
        msPatient -> redis "Recibe mensajes" "Redis Protocol"
        msPractitioner -> postgresql "Lee/escribe datos" "SQL/SSL"
        msPractitioner -> redis "Recibe mensajes" "Redis Protocol"
        msRoute -> postgresql "Lee/escribe datos" "SQL/SSL"
        msRoute -> redis "Recibe mensajes" "Redis Protocol"
        msRoute -> googleRoutes "Optimiza rutas" "HTTPS/REST"
        msEncounter -> postgresql "Lee/escribe datos" "SQL/SSL"
        msEncounter -> redis "Recibe mensajes" "Redis Protocol"
        msInstitutions -> postgresql "Lee/escribe datos" "SQL/SSL"
        msInstitutions -> redis "Recibe mensajes" "Redis Protocol"
        msCatalogs -> postgresql "Lee/escribe datos" "SQL/SSL"
        msCatalogs -> redis "Recibe mensajes" "Redis Protocol"

        msAuth -> sendgrid "Envía emails" "HTTPS/REST"
        flutterWeb -> firebaseHosting "Desplegado en" "CDN"

        # C3 Relationships (Component Level - API Gateway)
        authController -> commandBus "Ejecuta comandos"
        authController -> queryBus "Ejecuta queries"
        patientController -> commandBus "Ejecuta comandos"
        patientController -> queryBus "Ejecuta queries"
        routeController -> commandBus "Ejecuta comandos"

        commandBus -> loginHandler "Invoca"
        commandBus -> createPatientHandler "Invoca"
        queryBus -> getPatientByIdHandler "Invoca"

        loginHandler -> redisService "Comunica vía RPC"
        createPatientHandler -> redisService "Comunica vía RPC"
        getPatientByIdHandler -> redisService "Comunica vía RPC"

        jwtAuthGuard -> authController "Protege"
        jwtAuthGuard -> patientController "Protege"
        responseInterceptor -> authController "Intercepta"
        responseInterceptor -> patientController "Intercepta"

        # C3 Relationships (Component Level - ms-auth)
        authRpcController -> loginHandlerAuth "Ejecuta"
        authRpcController -> verifyEmailHandler "Ejecuta"

        loginHandlerAuth -> userRepository "Valida"
        loginHandlerAuth -> jwtStrategy "Genera"
        loginHandlerAuth -> refreshTokenRepository "Almacena tokens"
        loginHandlerAuth -> emailVerificationRepository "Crea código MFA"
        loginHandlerAuth -> emailService "Envía código MFA"

        verifyEmailHandler -> emailVerificationRepository "Valida código"
        verifyEmailHandler -> userRepository "Actualiza"

        # C3 Relationships (Component Level - hero-ms-route-nestjs)
        routeRpcController -> createRouteHandler "Ejecuta"
        visitRpcController -> createVisitHandler "Ejecuta"
        visitRpcController -> getVisitsHandler "Ejecuta"

        createRouteHandler -> googleRoutesService "Geocodifica"
        createRouteHandler -> routeOptimizerService "Optimiza"
        createRouteHandler -> routeRepository "Guarda"
        createRouteHandler -> visitRepository "Consulta"

        createVisitHandler -> visitRepository "Guarda"
        getVisitsHandler -> visitRepository "Consulta"

        routeOptimizerService -> googleRoutesService "Calcula distancias"
        googleRoutesService -> circuitBreakerService "Protege"

        # C3 Relationships (Component Level - ms-patient)
        patientRpcController -> msPatientCreatePatientHandler "Ejecuta"

        msPatientCreatePatientHandler -> caseNumberGenerator "Genera número"
        msPatientCreatePatientHandler -> riskClassifier "Clasifica riesgo"
        msPatientCreatePatientHandler -> patientRepository "Guarda"

        # C3 Relationships (Component Level - ms-practitioner)
        practitionerRpcController -> createPractitionerHandler "Ejecuta"
        specialtyRpcController -> specialtyRepository "Consulta"
        vehicleRpcController -> vehicleRepository "Consulta"
        agendaSlotRpcController -> getNetAvailabilityHandler "Ejecuta"

        createPractitionerHandler -> practitionerRepository "Guarda"
        createPractitionerHandler -> specialtyRepository "Valida especialidad"
        createPractitionerHandler -> vehicleRepository "Asigna vehículo"
        getNetAvailabilityHandler -> availabilityCalculator "Calcula"
        getNetAvailabilityHandler -> agendaSlotRepository "Consulta"

        # C3 Relationships (Component Level - ms-encounter)
        encounterRpcController -> createEncounterHandler "Ejecuta"
        procedureRpcController -> createProcedureHandler "Ejecuta"

        createEncounterHandler -> encounterRepository "Guarda"
        createProcedureHandler -> procedureManager "Valida"
        createProcedureHandler -> procedureRepository "Guarda"

        # C3 Relationships (Component Level - ms-institutions)
        institutionRpcController -> createInstitutionHandler "Ejecuta"
        zoneRpcController -> findZoneByCoordinatesHandler "Ejecuta"

        createInstitutionHandler -> institutionRepository "Guarda"
        findZoneByCoordinatesHandler -> zoneRepository "Busca"
        findZoneByCoordinatesHandler -> zoneManager "Gestiona"

        # C3 Relationships (Component Level - ms-catalogs)
        dynamicCatalogRpcController -> createDefinitionHandler "Ejecuta"
        dynamicCatalogRpcController -> getCatalogByCodeHandler "Ejecuta"

        createDefinitionHandler -> catalogManager "Gestiona"
        createDefinitionHandler -> dynamicCatalogRepository "Guarda"
        getCatalogByCodeHandler -> dynamicCatalogRepository "Consulta"
        stateRpcController -> hierarchyValidator "Valida jerarquías"
    }

    views {
        # C1 - Context View
        systemContext hero "C1-Context" {
            include *
            autoLayout
        }

        # C2 - Container View
        container hero "C2-Containers" {
            include *
            autoLayout
        }

        # C3 - Component Views
        component apiGateway "C3-APIGateway" {
            include *
            autoLayout
        }

        component msAuth "C3-MSAuth" {
            include *
            autoLayout
        }

        component msRoute "C3-MSRoute" {
            include *
            autoLayout
        }

        component msPatient "C3-MSPatient" {
            include *
            autoLayout
        }

        component msPractitioner "C3-MSPractitioner" {
            include *
            autoLayout
        }

        component msEncounter "C3-MSEncounter" {
            include *
            autoLayout
        }

        component msInstitutions "C3-MSInstitutions" {
            include *
            autoLayout
        }

        component msCatalogs "C3-MSCatalogs" {
            include *
            autoLayout
        }

        # Styles
        styles {
            element "Person" {
                background #08427B
                color #ffffff
                fontSize 22
                shape Person
            }
            element "Software System" {
                background #1168bd
                color #ffffff
            }
            element "External" {
                background #E74C3C
                color #ffffff
            }
            element "Container" {
                background #438dd5
                color #ffffff
            }
            element "API" {
                background #85C1E2
                color #000000
            }
            element "Microservice" {
                background #85C1E2
                color #000000
            }
            element "Database" {
                background #F39C12
                color #ffffff
                shape Cylinder
            }
            element "Cache/Message Broker" {
                background #E67E22
                color #ffffff
                shape Pipe
            }
            element "Infrastructure" {
                background #7F8C8D
                color #ffffff
            }
            element "Web Browser" {
                background #438dd5
                color #ffffff
            }
            element "Component" {
                background #9B59B6
                color #ffffff
            }
        }
    }

    configuration {
        scope softwareSystem
    }
}