Generador de Documento de Incorporación de Arquitectura de Codebase

**Contexto:** Soy un desarrollador que acaba de unirse al proyecto y te estoy usando a ti, un asistente de codificación con IA, para obtener una comprensión profunda del código base existente. Mi objetivo es volverme productivo lo más rápido posible y tomar decisiones técnicas informadas basadas en una comprensión sólida del sistema actual. **Objetivo Principal:** Analizar el código fuente proporcionado en este proyecto/espacio de trabajo y generar un documento Markdown detallado, claro y bien estructurado que explique la arquitectura del sistema, las características, los flujos principales, los componentes clave y la pila tecnológica. Este documento debe servir como una guía técnica de incorporación. Siempre que sea posible, mejora la navegabilidad proporcionando enlaces directos a archivos, clases y funciones relevantes, así como ejemplos de código que ayuden a aclarar los conceptos. --- ## Instrucciones Detalladas - Por favor, aborda los siguientes puntos: ### 1. Resumen de Archivos README / Instrucciones - Busca archivos como README.md, LEIAME.md, CONTRIBUTING.md o documentación similar. - Proporciona un resumen objetivo pero detallado de las secciones más relevantes para un nuevo desarrollador, incluyendo: - Descripción general del proyecto - Cómo configurar y ejecutar el sistema localmente - Estándares y convenciones adoptados - Guías de contribución (si están disponibles) --- ### 2. Pila Tecnológica Detallada - Identifica y enumera la pila tecnológica completa utilizada en el proyecto: - Lenguaje(s) de programación, incluyendo versiones cuando sean detectables (por ejemplo, desde package.json, pom.xml, .tool-versions, requirements.txt, build.gradle, etc.). - Frameworks principales (backend, frontend, etc. - por ejemplo, Spring Boot, .NET, React, Angular, Vue, Django, Rails). - Base(s) de datos: - Tipo (SQL / NoSQL) - Nombre (PostgreSQL, MongoDB, etc.) - Estilo de arquitectura central (por ejemplo, Monolito, Microservicios, Serverless, MVC, MVVM, Arquitectura Limpia). - Plataforma en la nube (si es identificable a través de SDKs o configuración - AWS, Azure, GCP). - Herramientas de compilación y gestores de paquetes (Maven, Gradle, npm, yarn, pip). - Cualquier otra tecnología relevante (caché, brokers de mensajes, contenedores - Docker, Kubernetes). - Haz referencia y enlaza los archivos de configuración que demuestren cada elemento. --- ### 3. Descripción General y Propósito del Sistema - Describe claramente qué hace el sistema y para quién es. - ¿Qué problemas resuelve? - Enumera las funcionalidades principales. - Si es posible, relaciona el sistema con los dominios de negocio involucrados. - Proporciona una descripción de alto nivel de las características principales. --- ### 4. Estructura del Proyecto y Recomendaciones de Lectura - Punto de Entrada: ¿Dónde debería empezar a explorar el código? Identifica los puntos de entrada principales (por ejemplo, main.go, index.js, Program.cs, app.py, Application.java). Proporciona enlaces directos a estos archivos. - Organización General: Explica la estructura general de carpetas y archivos. Destaca las convenciones importantes. Usa ejemplos reales de nombres de carpetas y archivos. - Configuración: ¿Hay archivos de configuración principales? (por ejemplo, config.yaml, .env, appsettings.json) ¿Qué configuraciones son críticas? Proporciona enlaces. - Recomendación de Lectura: Sugiere un orden o un conjunto de archivos/módulos clave que deberían leerse primero para comprender rápidamente los conceptos centrales del proyecto. --- ### 5. Componentes Clave - Identifica y describe los módulos, clases, funciones o servicios más importantes o centrales. - Explica las responsabilidades de cada componente. - Describe sus responsabilidades e interdependencias. - Para cada componente: - Incluye un fragmento de código representativo - Proporciona un enlace a dónde está implementado - Proporciona enlaces directos y ejemplos de código siempre que sea posible. --- ### 6. Flujos de Ejecución y Datos - Describe los flujos de trabajo o procesos de negocio más comunes o críticos (por ejemplo, procesamiento de pedidos, autenticación de usuarios). - Explica cómo fluyen los datos a través del sistema: - Dónde se persisten los datos - Cómo se leen, modifican y propagan - Siempre que sea posible, ilustra con ejemplos y enlaza a funciones o clases relevantes. #### 6.1 Descripción General del Esquema de Base de Datos (si aplica) - Para aplicaciones intensivas en datos: - Identifica las principales entidades/tablas/colecciones - Describe sus relaciones primarias - Basa esto en modelos ORM, migraciones o archivos de esquema si están disponibles --- ### 7. Dependencias e Integraciones - Dependencias: Enumera las principales bibliotecas externas, frameworks y SDKs utilizados. Explica brevemente el papel de cada uno. Proporciona enlaces a dónde están configurados o se usan más comúnmente. - Integraciones: Identifica y explica las integraciones con servicios externos, bases de datos adicionales, APIs de terceros, brokers de mensajes, etc. ¿Cómo ocurre la comunicación? Señala los módulos/clases responsables e incluye enlaces. #### 7.1 Documentación de API (si aplica) - Si el proyecto expone APIs: - ¿Hay evidencia de herramientas o estándares de documentación de API (por ejemplo, Swagger/OpenAPI, Javadoc, docstrings específicos de endpoints)? - ¿Dónde se puede encontrar esta documentación o cómo se puede generar? --- ### 8. Diagramas - Genera diagramas de alto nivel para visualizar la arquitectura y el comportamiento del sistema: - Diagrama de componentes (destacando los módulos principales y sus interacciones) - Diagrama de flujo de datos (mostrando cómo se mueve la información a través del sistema) - Diagrama de clases (mostrando clases clave y relaciones, si aplica) - Diagrama de despliegue simplificado (dónde se ejecutan los componentes, si es detectable) - Diagrama de infraestructura/despliegue simplificado (si los detalles de infraestructura son evidentes) - Crea estos diagramas usando sintaxis de Mermaid dentro del archivo Markdown. - Los diagramas deben ser de alto nivel; no se requiere un detalle extenso. --- ### 9. Pruebas - ¿Hay pruebas automatizadas? - Pruebas unitarias - Pruebas de integración - Pruebas de extremo a extremo (E2E) - ¿Dónde están ubicadas en el proyecto? - ¿Qué framework(s) de pruebas se utilizan? - ¿Cómo se ejecutan típicamente las pruebas? - ¿Cómo se pueden ejecutar las pruebas localmente? - ¿Hay alguna estrategia de CI/CD que involucre pruebas? --- ### 10. Manejo de Errores y Registro (Logging) - ¿Cómo maneja la aplicación los errores en general? - ¿Hay un patrón estándar (por ejemplo, middleware global, excepciones personalizadas)? - ¿Qué biblioteca de logging se utiliza? - ¿Hay un formato de logging estándar? - ¿Hay integración visible con herramientas de monitoreo (por ejemplo, Datadog, Sentry)? --- ### 11. Consideraciones de Seguridad - ¿Hay mecanismos de seguridad evidentes en el código? - Autenticación - Autorización (middleware/filtros) - Validación de entrada - ¿Se utilizan bibliotecas de seguridad específicas de manera prominente (por ejemplo, Spring Security, Passport.js, bibliotecas JWT)? - ¿Hay prácticas de seguridad notables? - Gestión de secretos - Protección contra ataques comunes --- ### 12. Otras Observaciones Relevantes (Incluyendo Compilación/Despliegue) - ¿Hay archivos relacionados con la compilación o el despliegue? - Dockerfile - docker-compose.yml - Scripts de compilación/despliegue - Archivos de configuración de CI/CD (por ejemplo, .github/workflows/, .gitlab-ci.yml) - ¿Qué indican estos archivos sobre cómo se compila y despliega la aplicación? - ¿Hay algo más crucial o particularmente útil para un nuevo desarrollador? - Deuda técnica conocida mencionada en comentarios - Patrones de diseño inusuales - Convenciones de codificación importantes - Notas de rendimiento --- ## Formato de Salida Final - Genera la respuesta completa como un documento Markdown (.md) bien formateado. - Usa un lenguaje claro y directo. - Organiza el contenido con títulos y subtítulos de acuerdo con las secciones numeradas anteriores. - Incluye fragmentos de código relevantes (cortos y representativos). - Incluye enlaces en los que se pueda hacer clic a archivos, funciones, clases y definiciones siempre que se mencione un elemento de código específico. - Estructura el documento usando las secciones numeradas anteriores para facilitar la lectura. Siempre que sea posible: - Incluye enlaces en los que se pueda hacer clic a archivos, funciones y clases. - Muestra fragmentos de código cortos y representativos. - Usa viñetas o tablas para las listas. --- ### IMPORTANTE El análisis debe considerar TODOS los archivos del proyecto. Lee y comprende todos los archivos necesarios para ejecutar completamente esta tarea y lograr una comprensión completa del sistema. --- ### Acción Por favor, analiza el código fuente actualmente disponible en mi entorno/espacio de trabajo y genera el documento Markdown como se solicita. El nombre del archivo de salida debe seguir este formato: <yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>