Instruction file imported from Salchichon057/C4_diagrams (.github/instructions/dsl-architecture.instructions.md). Copyright stays with the author.

🏗️ Instrucciones para Diagramas C4-DSL - Arquitectura Completa

🚨 REGLA CRÍTICA #1 - FIDELIDAD AL ENUNCIADO

⚠️ PRIORIDAD ABSOLUTA: Si existe un enunciado/caso de estudio, SIEMPRE seguir estas reglas:

📋 METODOLOGÍA DE ANÁLISIS DEL ENUNCIADO

1. LEER COMPLETO: Analizar todo el enunciado antes de empezar
2. EXTRAER TECNOLOGÍAS: Identificar todas las tecnologías específicas mencionadas
3. IDENTIFICAR ACTORES: Usuarios y roles explícitamente mencionados
4. MAPEAR FUNCIONALIDADES: Solo implementar características del enunciado
5. VERIFICAR PATRONES: Si menciona CQRS, Event Sourcing, etc., implementarlo

🎯 IMPLEMENTACIÓN OBLIGATORIA

// ✅ CORRECTO - Solo lo que está en el enunciado
// Si el enunciado dice: "Angular para web, Flutter para móvil, .NET Core, SQL Server, Azure AD"

webApp = container "Web Application" "Angular SPA" "Según enunciado específico" {
  tags "WEB"
}
mobileApp = container "Mobile App" "Flutter Application" "Según enunciado específico" {
  tags "WEB"
}
apiService = container "API Service" ".NET Core Microservice" "Según enunciado específico" {
  tags "API Gateway"
}
mainDB = container "Main Database" "SQL Server" "Según enunciado específico" {
  tags "BD"
}

// ❌ INCORRECTO - Agregar tecnologías no mencionadas
redisCache = container "Redis Cache" "Redis" "NO ESTÁ EN EL ENUNCIADO"
messageBroker = container "Message Broker" "Apache Kafka" "NO ESTÁ EN EL ENUNCIADO"

🔍 PATRONES ARQUITECTÓNICOS ESPECÍFICOS

Si el enunciado menciona patrones específicos, implementarlos EXACTAMENTE:

CQRS (Command Query Responsibility Segregation):

// Si menciona "CQRS", separar bases de datos read/write
writeDatabase = container "Write Database" "SQL Server" "BD de escritura para comandos" {
  tags "BD"
}
readDatabase = container "Read Database" "SQL Server" "BD de lectura para consultas" {
  tags "BD"
}

// Relaciones CQRS
service -> writeDatabase "Comandos de escritura" "SQL"
service -> readDatabase "Consultas de lectura" "SQL"

Event Sourcing:

// Si menciona "Event Sourcing", implementar store de eventos
eventStore = container "Event Store" "SQL Server/EventStore" "Almacén de eventos de dominio" {
  tags "BD"
}

🚫 ERRORES COMUNES A EVITAR

1. ❌ Sobre-arquitectura: No agregar microservicios no mencionados
2. ❌ Tecnologías no especificadas: No agregar Redis, Kafka, etc. si no están
3. ❌ Interfaces adicionales: No separar dashboards si no se mencionan
4. ❌ Servicios extras: No agregar servicios de alertas si no están especificados
5. ❌ Componentes de infraestructura: No agregar cache, CDN sin justificación

✅ VERIFICACIÓN FINAL - CHECKLIST OBLIGATORIO

Antes de entregar, verificar:

• ¿Cada contenedor está justificado en el enunciado?
• ¿Las tecnologías coinciden exactamente?
• ¿Los actores son los mencionados?
• ¿Los patrones arquitectónicos son los especificados?
• ¿No agregué componentes "nice to have"?

📊 EJEMPLO PRÁCTICO - Smart Farming Solutions

Enunciado dice: ".NET Core, Angular, Flutter, SQL Server, CQRS, Azure AD, Azure IoT Hub"
✅ IMPLEMENTAR: Exactamente esas tecnologías
❌ NO AGREGAR: Redis, Kafka, Analytics Dashboard separado, ML Pipeline independiente

📋 Estructura Estándar del Archivo DSL

1. Workspace Structure

workspace {
  model {
    // 1. Personas/Actores
    // 2. Sistemas Externos
    // 3. Sistema Principal
    // 4. Relaciones (Sistema → Sistema)
    // 5. Relaciones (Contenedor → Contenedor)
  }
  
  views {
    // 1. System Context (C1)
    // 2. Container Views (C2)
    // 3. Component Views (C3) - si es necesario
    // 4. Estilos personalizados
  }
  
  properties {
    // Metadatos del workspace
  }
}

🎭 Definición de Actores/Personas

Tipos de Usuarios Estándar:

• Usuarios Finales: endUser, customer, buyer, seller
• Administradores: admin, superAdmin, operator
• Desarrolladores: developer, devOps, sysAdmin
• Sistemas: externalSystem, legacySystem, thirdParty

// Ejemplo de definición de personas
endUser = person "Usuario Final" "Persona que usa la aplicación."
admin = person "Administrador" "Gestiona y configura el sistema."
developer = person "Desarrollador" "Desarrolla y mantiene el sistema."

🏢 Sistemas y Categorización por Tags

📱 Frontend/Interfaces (WEB)

webApp = container "Web Application" "SPA/React/Vue" "Interfaz web principal." {
  tags "WEB"
}
mobileApp = container "Mobile App" "React Native/Flutter" "Aplicación móvil nativa." {
  tags "WEB"  
}
dashboard = container "Admin Dashboard" "Angular/React" "Panel administrativo." {
  tags "WEB"
}

🔷 APIs y Gateways (API Gateway)

apiGateway = container "API Gateway" "Kong/Zuul/AWS API Gateway" "Punto de entrada unificado." {
  tags "API Gateway"
}
restAPI = container "REST API" "Spring Boot/Express" "API RESTful principal." {
  tags "API Gateway"
}
graphqlAPI = container "GraphQL API" "Apollo/Hasura" "API GraphQL para consultas flexibles." {
  tags "API Gateway"
}
webhookAPI = container "Webhook API" "Express/FastAPI" "Recibe notificaciones externas." {
  tags "API Gateway"
}

🔐 Autenticación y Autorización (AUTENTICACIÓN)

authService = container "Auth Service" "Keycloak/Auth0" "Autenticación centralizada." {
  tags "AUTENTICACIÓN"
}
identityProvider = container "Identity Provider" "LDAP/AD" "Proveedor de identidades." {
  tags "AUTENTICACIÓN"
}
jwtService = container "JWT Service" "Custom/Library" "Generación y validación de tokens." {
  tags "AUTENTICACIÓN"
}
rbacService = container "RBAC Service" "Custom" "Control de acceso basado en roles." {
  tags "AUTENTICACIÓN"
}

🔄 Integración y Mensajería (ESB)

messageBroker = container "Message Broker" "Apache Kafka/RabbitMQ" "Bus de mensajes async." {
  tags "ESB"
}
eventBus = container "Event Bus" "Apache Kafka/AWS EventBridge" "Bus de eventos de dominio." {
  tags "ESB"
}
serviceRegistry = container "Service Registry" "Eureka/Consul" "Registro de servicios." {
  tags "ESB"
}
loadBalancer = container "Load Balancer" "NGINX/HAProxy" "Distribuidor de carga." {
  tags "ESB"
}

🤖 Inteligencia Artificial (Servicio de IA)

aiService = container "AI Service" "TensorFlow/PyTorch" "Servicio de machine learning." {
  tags "Servicio de IA"
}
ragSystem = container "RAG System" "LangChain/LlamaIndex" "Retrieval Augmented Generation." {
  tags "Servicio de IA"
}
vectorDB = container "Vector Database" "Pinecone/Weaviate" "BD vectorial para embeddings." {
  tags "Servicio de IA"
}
llmService = container "LLM Service" "OpenAI/Anthropic" "Servicio de modelo de lenguaje." {
  tags "Servicio de IA"
}
mlPipeline = container "ML Pipeline" "MLflow/Kubeflow" "Pipeline de machine learning." {
  tags "Servicio de IA"
}
chatbot = container "Chatbot" "Rasa/Dialogflow" "Asistente conversacional." {
  tags "Servicio de IA"
}

🗄️ Bases de Datos (BD)

primaryDB = container "Primary Database" "PostgreSQL/MySQL" "Base de datos principal." {
  tags "BD"
}
documentDB = container "Document Database" "MongoDB/CouchDB" "BD de documentos NoSQL." {
  tags "BD"
}
timeSeriesDB = container "Time Series DB" "InfluxDB/TimescaleDB" "BD para series temporales." {
  tags "BD"
}
graphDB = container "Graph Database" "Neo4j/ArangoDB" "Base de datos de grafos." {
  tags "BD"
}

📦 Almacenamiento (ALMACENAMIENTO)

blobStorage = container "Blob Storage" "AWS S3/Azure Blob" "Almacenamiento de archivos." {
  tags "ALMACENAMIENTO"
}
fileSystem = container "File System" "NFS/GlusterFS" "Sistema de archivos distribuido." {
  tags "ALMACENAMIENTO"
}
dataLake = container "Data Lake" "AWS S3/HDFS" "Lago de datos para analytics." {
  tags "ALMACENAMIENTO"
}

⚡ Cache (CACHE)

redisCache = container "Redis Cache" "Redis/ElastiCache" "Cache en memoria distribuido." {
  tags "CACHE"
}
memoryCache = container "Memory Cache" "Caffeine/Hazelcast" "Cache en memoria local." {
  tags "CACHE"
}
sessionStore = container "Session Store" "Redis/Hazelcast" "Almacén de sesiones." {
  tags "CACHE"
}

🌐 CDN y Distribución (CDN)

cdn = container "CDN" "CloudFlare/AWS CloudFront" "Red de distribución de contenido." {
  tags "CDN"
}
staticHosting = container "Static Hosting" "Vercel/Netlify" "Hosting de contenido estático." {
  tags "CDN"
}

🔗 Patrones de Relaciones Estándar

Usuario → Sistema

user -> system "Acción principal" "HTTPS"
admin -> system "Administra" "HTTPS"

Sistema → Sistema

systemA -> systemB "Consume servicios de" "HTTPS"
systemA -> systemB "Publica eventos a" "Message Queue"

Contenedor → Contenedor

// Frontend → Backend
webApp -> apiGateway "Consume API" "HTTPS"
mobileApp -> restAPI "Llama servicios" "HTTPS"

// Backend → Datos
restAPI -> primaryDB "Lee/Escribe" "JDBC/SQL"
service -> redisCache "Cache datos" "Redis Protocol"

// Async/Eventos
service -> messageBroker "Publica eventos" "Kafka"
worker -> messageBroker "Consume eventos" "Kafka"

// AI/ML
service -> aiService "Solicita predicción" "HTTP/gRPC"
aiService -> vectorDB "Consulta embeddings" "Vector Query"

📊 Vistas Recomendadas

C1 - System Context

systemContext mainSystem "SystemContext" {
  include mainSystem
  include *  // Todos los actores y sistemas externos
  title "Contexto del Sistema"
  description "Vista de alto nivel mostrando actores y sistemas externos"
}

C2 - Container View

container mainSystem "ContainerView" {
  include *  // ⚠️ CRÍTICO: NUNCA excluir sistemas externos en vista de contenedores
  title "Vista de Contenedores"
  description "Contenedores internos y sus relaciones con sistemas externos"
}

⚠️ REGLAS CRÍTICAS PARA VISTAS C2 - CONTAINER

🚫 ERROR COMÚN - NO EXCLUIR SISTEMAS EXTERNOS

// ❌ INCORRECTO - No excluir sistemas externos
container mainSystem "ContainerView" {
  include *
  exclude externalSystem1 externalSystem2  // ¡ERROR CRÍTICO!
}

// ✅ CORRECTO - Incluir todo para mostrar integraciones
container mainSystem "ContainerView" {
  include *  // Muestra contenedores internos Y sistemas externos
  title "Vista de Contenedores"
  description "Arquitectura interna y sus relaciones con sistemas externos"
}

🎯 PROPÓSITO DE LA VISTA DE CONTENEDORES

La vista C2 debe mostrar:

• ✅ Contenedores internos del sistema principal
• ✅ Sistemas externos (Azure, AWS, APIs de terceros, etc.)
• ✅ Relaciones directas contenedor → sistema externo
• ✅ Actores/usuarios → contenedores específicos

📋 EJEMPLO CORRECTO COMPLETO

// Usuarios se relacionan directamente con contenedores
user -> webApp "Accede a la interfaz web" "HTTPS"
user -> mobileApp "Usa aplicación móvil" "HTTPS"

// Contenedores se relacionan con sistemas externos
apiGateway -> azureAD "Autenticación" "OAuth2"
dataService -> azureStorage "Almacena archivos" "HTTPS"
iotService -> azureIoTHub "Recibe datos IoT" "MQTT"

// Vista C2 incluye TODO
container mainSystem "ContainerView" {
  include *  // Contenedores + Sistemas externos + Usuarios
  title "C2 - Contenedores"
  description "Arquitectura interna y relaciones externas"
}

🎯 Consideraciones Arquitectónicas Completas

🔄 Patrones de Integración

• Event-Driven: Message brokers, Event sourcing
• API-First: REST, GraphQL, gRPC
• Microservices: Service mesh, Discovery
• Serverless: Functions, Event triggers

🛡️ Seguridad

• Autenticación: OAuth2, SAML, JWT
• Autorización: RBAC, ABAC, Policy engines
• Cifrado: TLS, Encryption at rest
• Monitoreo: Security logs, SIEM

📈 Observabilidad

• Logs: Centralized logging (ELK, Fluentd)
• Métricas: Prometheus, Grafana
• Trazas: Jaeger, Zipkin
• Alertas: PagerDuty, Slack notifications

⚡ Performance

• Cache: Multi-layer caching strategy
• CDN: Global content distribution
• Load Balancing: Horizontal scaling
• Database: Read replicas, Sharding

🤖 AI/ML Components

• Data Pipeline: ETL/ELT processes
• Feature Store: ML feature management
• Model Registry: Version control for models
• A/B Testing: Experiment framework
• RAG System: Knowledge base + LLM

📊 Analytics y Business Intelligence

• Data Warehouse: Snowflake, BigQuery
• ETL Pipeline: Apache Airflow, dbt
• Real-time Analytics: Apache Spark, Flink
• Dashboard: Tableau, PowerBI

✅ Checklist de Completitud Arquitectónica

Frontend/UX

• Web Application
• Mobile Apps
• Admin Dashboard
• Progressive Web App (PWA)

Backend Services

• API Gateway
• Authentication Service
• Business Logic Services
• Background Workers
• Webhook Handlers

Data Layer

• Primary Database
• Cache Layer
• Search Engine
• File Storage
• Backup Strategy

Integration

• Message Broker/Event Bus
• Service Discovery
• Load Balancer
• Circuit Breakers

AI/ML (si aplica)

• ML Model Services
• Vector Database
• RAG System
• Feature Store
• Model Pipeline

External Systems

• Payment Processors
• Email Services
• SMS/Push Notifications
• Third-party APIs
• Legacy System Integrations

Infrastructure

• CDN
• Monitoring/Logging
• Security Scanner
• Backup/Recovery
• Health Checks

DevOps/Deployment

• CI/CD Pipeline
• Container Registry
• Configuration Management
• Secret Management

🎨 Aplicación Automática de Estilos

Usar los tags definidos en styles.instructions.md para categorizar automáticamente todos los contenedores según su función arquitectónica.

📚 METODOLOGÍA DE TRABAJO CON ENUNCIADOS

🔍 FASE 1: ANÁLISIS DEL CASO DE ESTUDIO

1. Lectura completa: Leer todo el enunciado 2-3 veces
2. Extracción de tecnologías: Crear lista de todas las tecnologías mencionadas
3. Identificación de patrones: Buscar CQRS, Event Sourcing, microservicios, etc.
4. Mapeo de actores: Identificar todos los tipos de usuarios
5. Funcionalidades core: Listar solo las características especificadas

🎯 FASE 2: DISEÑO ARQUITECTÓNICO

1. Crear actores: Solo los mencionados en el enunciado
2. Definir sistemas externos: Basados en tecnologías especificadas
3. Diseñar contenedores: Usando las tecnologías exactas del enunciado
4. Implementar patrones: CQRS, Event Sourcing, etc. si se mencionan
5. Establecer relaciones: Basadas en flujos descritos

✅ FASE 3: VALIDACIÓN

1. Auditoría de fidelidad: ¿Todo está en el enunciado?
2. Verificación tecnológica: ¿Las tecnologías coinciden?
3. Revisión de patrones: ¿Los patrones están bien implementados?
4. Eliminación de extras: Remover componentes no justificados

🚨 SEÑALES DE ALERTA - REVISAR SI:

• Agregaste más de 6-8 microservicios sin justificación
• Incluiste tecnologías no mencionadas (Redis, Kafka, etc.)
• Separaste interfaces sin base en el enunciado
• Implementaste patrones no especificados
• Creaste múltiples bases de datos sin CQRS explícito

Nota: Esta guía prioriza la fidelidad al enunciado por encima de la completitud arquitectónica. Cuando hay un caso de estudio específico, seguir sus especificaciones es más importante que implementar una arquitectura "completa" genérica.