> Esta traducción se ofrece por comodidad. El texto normativo es el original en inglés. # Estructura del repositorio **Especificación del Meta-Universo** **ID del documento:** MU-V2-GUIDE-002 **Título:** Arquitectura del repositorio semántico **Clase de documento:** informativo **Versión:** 2.0 (borrador) **Estado:** borrador de trabajo **Referencias normativas:** MMAS **Referencias informativas:** Getting-Started, Create-a-New-Meta-Model **Copyright:** © Orkestron.AI **Licencia:** Apache-2.0 --- # 1. Propósito Esta guía explica la estructura de repositorio recomendada del Meta-Universo y el papel de cada carpeta principal. La disposición del repositorio está pensada para que la entiendan tanto las personas como los agentes de IA, y para sostener la evolución a largo plazo, la trazabilidad y la federación semántica. Las contrapartes normativas de esta guía son [MMAS-Package](../02-architecture/MMAS-Package.md) (la disposición canónica), [Model-Traversal-and-Layout](../02-architecture/Model-Traversal-and-Layout.md) (el contrato de recorrido sin pérdidas y las ubicaciones reservadas para arranques, canon, datos crudos y artefactos) y [Data-Mastership](../02-architecture/Data-Mastership.md) (qué sistema es el maestro de cada conjunto de datos). --- # 2. Objetivos de diseño Se espera que un repositorio del Meta-Universo sea: - nativo de Git; - modular; - organizado semánticamente; - versionado; - trazable; - fácil de recorrer. La organización del repositorio refleja la arquitectura semántica, no la tecnología de implementación. --- # 2a. Arquitectura del repositorio semántico La idea que define a un repositorio del Meta-Universo es que está organizado **por semántica, no por tipo de fichero ni por tecnología**. Los repositorios de software convencionales agrupan los ficheros por lo que *son*: `src/`, `docs/`, `tests/`, `lib/`, `config/`. Un repositorio del Meta-Universo agrupa en cambio los documentos por la *pregunta que responden*. Cada carpeta de primer nivel es una pregunta; su contenido es la respuesta. - `00-foundation`: **por qué** existe el estándar; - `01-constitution`: **qué leyes** obedece; - `02-architecture`: **cómo** está construido; - `03-federation`: **cómo** interactúa con otros; - `04-core-concepts`: **qué conceptos fundamentales** usa; - `05-reference-architecture`: **cómo** aplicarlo; - `06-ecosystem`: **cómo** vive en el ecosistema más amplio; - `07-guides`: **cómo** empezar; - `examples`: **cómo** se ve en la práctica. Como cada carpeta corresponde a una pregunta y no a una tecnología, el repositorio se convierte en un **espacio semántico** y no en un árbol de ficheros. Quien llega nuevo puede navegar por intención ("necesito saber cómo federa este modelo" → `03-federation`), y también puede hacerlo un agente de IA, que asigna carpetas a preguntas y localiza el conocimiento pertinente sin analizar extensiones de fichero. Reorganizar por tecnología dispersaría la respuesta a una sola pregunta por muchas carpetas; organizar por semántica mantiene entera cada respuesta. Es el mismo principio que los estándares aplican a los meta-modelos - modela primero el significado - aplicado al propio repositorio. --- # 3. Estructura recomendada ``` Repository/ ├── README.md ├── LICENSE ├── CHANGELOG.md ├── archive/ ├── 00-foundation/ ├── 01-constitution/ ├── 02-architecture/ ├── 03-federation/ ├── 04-core-concepts/ ├── 05-reference-architecture/ ├── 06-ecosystem/ ├── 07-guides/ ├── examples/ └── schemas/ (optional) ``` --- # 4. Ficheros de la raíz **README.md** Punto de entrada al repositorio. **LICENSE** Condiciones de publicación y reutilización. **CHANGELOG.md** Historia de las versiones publicadas. --- # 5. archive/ Guarda publicaciones anteriores que siguen disponibles como referencia histórica. Su contenido no se modifica una vez archivado. --- # 6. 00-foundation/ Contiene el fundamento conceptual: - Visión - Principios - Terminología - Glosario Lee estos documentos primero. --- # 7. 01-constitution/ Define las reglas constitucionales del ecosistema: - Constitución - Gobernanza - Proceso de cambio - Conformidad Estos documentos responden a *qué debe seguir siendo cierto siempre*. --- # 8. 02-architecture/ Contiene las especificaciones de MMAS que describen cómo se construyen los meta-modelos. Entre los temas típicos están: - el versionado; - los nombres; - la trazabilidad; - la validación; - la estructura de paquete. --- # 9. 03-federation/ Contiene las especificaciones de MUFP que describen la colaboración semántica entre Universos independientes. Entre los temas típicos están: - la confianza; - la vinculación de identidades; - la sincronización; - la correspondencia semántica; - el ciclo de vida de la federación. --- # 10. 04-core-concepts/ Define el vocabulario semántico común que comparten todos los meta-modelos. Incluye conceptos como: - Universo; - Objeto; - Relación; - Proyección; - Contexto; - Suceso; - Ciclo de vida. --- # 11. 05-reference-architecture/ Ofrece orientación arquitectónica reutilizable. Entre los documentos típicos están: - la arquitectura; - la pila; - los patrones de interacción; - los patrones de federación; - los patrones de ciclo de vida; - los diagramas de referencia. --- # 12. 06-ecosystem/ Describe capacidades a nivel de ecosistema. Entre los temas típicos están: - los registros; - la compatibilidad; - la certificación; - las implementaciones; - la hoja de ruta. --- # 13. 07-guides/ Contiene orientación práctica. Ejemplos: - Primeros pasos; - Estructura del repositorio; - Guías de migración; - Guías de publicación. Las guías complementan las especificaciones normativas. --- # 14. examples/ Contiene ejemplos ilustrativos que muestran la aplicación correcta de los estándares. Los ejemplos se mantienen sincronizados con las especificaciones vigentes. --- # 15. schemas/ (opcional) Puede contener activos legibles por máquina: - JSON Schema; - YAML; - OpenAPI; - OData; - artefactos de validación. Los esquemas remiten a los documentos normativos. --- # 16. Estrategia de navegación Orden de lectura recomendado: 1. README 2. Fundamento 3. Constitución 4. Arquitectura 5. Federación 6. Conceptos nucleares 7. Arquitectura de referencia 8. Ecosistema 9. Guías 10. Ejemplos --- # 17. Buenas prácticas A quienes mantienen un repositorio se les anima a: - mantener los documentos enfocados; - separar el contenido normativo del informativo; - conservar las versiones históricas; - mantener estables los nombres de fichero; - publicar metadatos de versión; - automatizar la validación donde sea practicable. --- # 18. Declaración final Un repositorio bien estructurado es esencial para la localizabilidad, la interoperabilidad y el mantenimiento a largo plazo. Siguiendo la organización de repositorio recomendada por el Meta-Universo, quienes publican crean repositorios fáciles de entender, validar, extender y federar, lo que permite que tanto las personas como los agentes de IA recorran el conocimiento semántico de forma coherente por todo el ecosistema.