Exportar e Importar Proyectos: Tu Arquitectura, Completamente Portable

Creemos que tu documentación de arquitectura te pertenece. No bloqueada en un formato propietario, no atrapada detrás de una API, no retenida como rehén por un nivel de suscripción. Si has invertido tiempo documentando tus sistemas, contenedores, componentes y relaciones, deberías poder llevarte ese trabajo contigo.

Hoy, hacemos esa creencia concreta. Archyl ahora soporta exportación e importación completa de proyectos.

Todo en Un Archivo

Cuando exportas un proyecto, obtienes un solo archivo JSON conteniendo todo tu modelo C4. Cada sistema que has definido, cada contenedor dentro de esos sistemas, cada componente, hasta elementos de nivel código si has modelado a esa profundidad. Las relaciones que los conectan, con sus descripciones y anotaciones de tecnología. Los overlays visuales que has creado para agrupar y organizar tus diagramas.

La exportación preserva el diseño espacial de tus diagramas. Has pasado tiempo posicionando elementos para comunicar estructura claramente—el API gateway a la izquierda, bases de datos a la derecha, sistemas externos arriba. Esa disposición no es aleatoria; es parte de cómo comunicas tu arquitectura. La exportación captura todo eso.

El formato es JSON simple, versionado y documentado. Ábrelo en cualquier editor de texto y puedes leerlo. Parsea con un script si quieres hacer algo personalizado. Son tus datos en un formato que controlas.

Cómo Funciona la Exportación

Abre cualquier proyecto al que tengas acceso, navega a la opción de exportar, y elige tu formato. Para portabilidad de datos, selecciona JSON. El archivo se descarga inmediatamente—incluso proyectos grandes con cientos de elementos se exportan en segundos.

También soportamos exportaciones visuales para diferentes casos de uso. SVG te da un formato vectorial que puedes editar en Illustrator o embeber en documentación. PNG proporciona una imagen compartible. PDF crea un documento profesional. Incluso hay una opción para combinar los cuatro niveles C4 en una sola exportación comprehensiva.

Para automatización, el endpoint de API funciona exactamente como esperarías. Una petición GET a /projects/{id}/export devuelve el payload JSON completo. Constrúyelo en tu pipeline CI, programa respaldos semanales, o intégralo con cualquier workflow que ya tengas.

La Importación Crea Proyectos Nuevos

Cuando importas una arquitectura, Archyl crea un proyecto completamente nuevo. Proporcionas un nombre y slug, opcionalmente seleccionas un equipo, y subes tu archivo JSON. El sistema parsea la exportación, valida su estructura, y recrea cada elemento con identificadores nuevos.

Esta es una decisión de diseño deliberada. La importación no fusiona en proyectos existentes ni intenta reconciliar conflictos. Crea una copia limpia, independiente de la fuente. El proyecto original continúa sin cambios; el proyecto importado comienza su propia vida.

El proceso de importación maneja la complejidad del remapeo de IDs de forma transparente. Tu exportación contiene los UUIDs originales de cuando los elementos fueron creados. La importación genera nuevos UUIDs para todo mientras preserva las relaciones entre elementos. Un contenedor que pertenecía a un sistema específico sigue perteneciendo a ese sistema. Una relación que conectaba dos componentes sigue conectándolos. La estructura es idéntica; solo los identificadores cambian.

Si una relación en la exportación referencia un elemento que no existe—quizás de una exportación parcial o un archivo corrupto—la importación registra una advertencia y continúa. Obtendrás todo lo que pudo ser importado, con visibilidad sobre lo que fue omitido.

Casos de Uso Reales

Una firma de consultoría con la que trabajamos usa exportación para entregar documentación de arquitectura a clientes. Modelan el sistema del cliente en Archyl, lo refinan a través de descubrimiento y documentación manual, y luego exportan el resultado final. El cliente recibe un archivo JSON que puede importar en su propia instancia de Archyl o simplemente archivar como registro del compromiso.

Un equipo de plataforma empresarial exporta su arquitectura semanalmente a un sistema de respaldo interno. Si algo sale mal con su documentación primaria, pueden restaurar desde la última exportación. El formato JSON significa que el respaldo es legible y verificable, no un blob binario opaco.

Una startup usó exportación durante una adquisición. La empresa adquirente necesitaba entender la arquitectura del sistema objetivo. En lugar de programar semanas de reuniones de transferencia de conocimiento, el equipo exportó su proyecto de Archyl y compartió el archivo. Los adquirentes lo importaron, lo exploraron interactivamente, y llegaron a las discusiones de integración con verdadero entendimiento de lo que estaban comprando.

Los equipos de desarrollo usan exportación como snapshots de arquitectura. Después de un release mayor, exportan el estado actual y hacen commit del archivo JSON junto con el código. Meses después, cuando alguien pregunta "¿cómo se veía la arquitectura antes de la migración a microservicios?", la respuesta está a un git checkout de distancia.

Qué Se Exporta

La exportación incluye la jerarquía C4 completa. Sistemas en el nivel superior, con contenedores anidados dentro, componentes dentro de contenedores, y elementos de código dentro de componentes. Cada elemento lleva sus metadatos completos: nombre, descripción, tipo, stack tecnológico, tags, coordenadas de posición, y cualquier estilo personalizado.

Las relaciones se exportan con ambos endpoints especificados, junto con su tipo, descripción y propiedades visuales como posiciones de etiquetas. El proceso de importación las mapea a los elementos recién creados, manteniendo la estructura exacta de conexiones.

Los overlays—las agrupaciones visuales que creas para organizar diagramas complejos—están incluidos con sus posiciones, dimensiones, colores, y los elementos que contienen.

Lo que actualmente no se exporta: ADRs, documentación de proyecto, user flows, y conexiones de repositorio. La exportación se enfoca en el modelo C4 mismo—los sistemas, contenedores, componentes, código, y sus relaciones. Estamos considerando expandir el alcance en futuros releases basándonos en lo que los usuarios nos dicen que necesitan.

Sin Lock-In, Sin Trucos

El formato de exportación usa versión "1.0" hoy. A medida que agregamos características, actualizaremos el formato mientras mantenemos compatibilidad hacia atrás. Una exportación que crees hoy importará correctamente años después, incluso cuando Archyl evolucione.

No estamos interesados en atrapar tus datos. Estamos interesados en ser suficientemente útiles para que elijas quedarte. Exportar e importar son nuestro compromiso con esa filosofía. Si Archyl deja de ser la herramienta correcta para ti, toma tu arquitectura y vete. Si un competidor construye algo mejor, hemos hecho fácil el cambio. La presión está en nosotros para seguir ganando tu confianza.

Primeros Pasos

Exportar e importar están disponibles en todos los planes, incluyendo Gratis. No hay restricciones artificiales, no hay juegos de "exportar es una característica premium".

Para exportar: abre cualquier proyecto, encuentra el botón de exportar, selecciona JSON, y guarda el archivo.

Para importar: desde tu lista de proyectos, haz clic en Importar, sube un archivo JSON, dale un nombre a tu nuevo proyecto, y confirma.

Tu documentación de arquitectura es tuya. Ahora puedes llevarla a donde sea.

¿Quieres aprender más sobre lo que puedes documentar en Archyl? Lee nuestra Introducción al Modelo C4 o ve cómo el Descubrimiento Impulsado por IA puede mapear automáticamente tus sistemas existentes.