Exportação e Importação de Projetos: Sua Arquitetura, Totalmente Portátil

Acreditamos que sua documentação de arquitetura pertence a você. Não presa em um formato proprietário, não trancada atrás de uma API, não refém de um nível de assinatura. Se você investiu tempo documentando seus sistemas, containers, componentes e relacionamentos, você deveria poder levar esse trabalho com você.

Hoje, estamos tornando essa crença concreta. O Archyl agora suporta exportação e importação completa de projetos.

Tudo em Um Arquivo

Quando você exporta um projeto, recebe um único arquivo JSON contendo todo o seu modelo C4. Cada sistema que definiu, cada container dentro desses sistemas, cada componente, até elementos de código se você modelou nessa profundidade. Os relacionamentos conectando-os, com suas descrições e anotações de tecnologia. Os overlays visuais que você criou para agrupar e organizar seus diagramas.

A exportação preserva o layout espacial dos seus diagramas. Você passou tempo posicionando elementos para comunicar estrutura claramente — o API gateway à esquerda, bancos de dados à direita, sistemas externos no topo. Essa disposição não é aleatória; é parte de como você comunica sua arquitetura. A exportação captura tudo.

O formato é JSON direto, versionado e documentado. Abra em qualquer editor de texto e você pode lê-lo. Parse com um script se quiser fazer algo personalizado. São seus dados em um formato que você controla.

Como a Exportação Funciona

Abra qualquer projeto que você tem acesso, navegue até a opção de exportação e escolha seu formato. Para portabilidade de dados, selecione JSON. O arquivo faz download imediatamente — mesmo projetos grandes com centenas de elementos exportam em segundos.

Também suportamos exportações visuais para diferentes casos de uso. SVG fornece um formato vetorial que você pode editar no Illustrator ou embutir em documentação. PNG fornece uma imagem compartilhável. PDF cria um documento profissional. Existe até uma opção para combinar todos os quatro níveis C4 em uma única exportação abrangente.

Para automação, o endpoint da API funciona exatamente como você esperaria. Uma requisição GET para /projects/{id}/export retorna o payload JSON completo. Integre no seu pipeline de CI, agende backups semanais ou integre com qualquer workflow que já tenha.

Importação Cria Projetos Novos

Quando você importa uma arquitetura, o Archyl cria um projeto completamente novo. Você fornece um nome e slug, opcionalmente seleciona uma equipe, e faz upload do seu arquivo JSON. O sistema faz parse da exportação, valida sua estrutura e recria cada elemento com identificadores novos.

Essa é uma escolha de design deliberada. A importação não faz merge em projetos existentes nem tenta reconciliar conflitos. Ela cria uma cópia limpa, independente da fonte. O projeto original continua inalterado; o projeto importado começa sua própria vida.

O processo de importação lida com a complexidade do remapeamento de IDs de forma transparente. Sua exportação contém os UUIDs originais de quando os elementos foram criados. A importação gera novos UUIDs para tudo enquanto preserva os relacionamentos entre elementos. Um container que pertencia a um sistema específico ainda pertence a esse sistema. Um relacionamento que conectava dois componentes ainda os conecta. A estrutura é idêntica; apenas os identificadores mudam.

Se um relacionamento na exportação referencia um elemento que não existe — talvez de uma exportação parcial ou arquivo corrompido — a importação registra um aviso e continua. Você receberá tudo que pôde ser importado, com visibilidade do que foi pulado.

Casos de Uso Reais

Uma consultoria com quem trabalhamos usa a exportação para entregar documentação de arquitetura a clientes. Eles modelam o sistema do cliente no Archyl, refinam através de descoberta e documentação manual, e depois exportam o resultado final. O cliente recebe um arquivo JSON que pode importar na sua própria instância do Archyl ou simplesmente arquivar como registro do trabalho.

Uma equipe de plataforma empresarial exporta sua arquitetura semanalmente para um sistema de backup interno. Se algo der errado com sua documentação principal, podem restaurar da última exportação. O formato JSON significa que o backup é legível e verificável, não um blob binário opaco.

Uma startup usou a exportação durante uma aquisição. A empresa compradora precisava entender a arquitetura do sistema alvo. Ao invés de agendar semanas de reuniões de transferência de conhecimento, a equipe exportou seu projeto do Archyl e compartilhou o arquivo. Os compradores importaram, exploraram interativamente e chegaram às discussões de integração com entendimento real do que estavam comprando.

Equipes de desenvolvimento usam a exportação como snapshots de arquitetura. Após um release importante, exportam o estado atual e commitam o arquivo JSON junto com o código. Meses depois, quando alguém pergunta "como era a arquitetura antes da migração para microsserviços?", a resposta está a um git checkout de distância.

O Que É Exportado

A exportação inclui a hierarquia C4 completa. Sistemas no nível mais alto, com containers aninhados dentro, componentes dentro dos containers, e elementos de código dentro dos componentes. Cada elemento carrega seus metadados completos: nome, descrição, tipo, stack tecnológico, tags, coordenadas de posição e qualquer estilização personalizada.

Relacionamentos são exportados com ambos os endpoints especificados, junto com seu tipo, descrição e propriedades visuais como posições de label. O processo de importação mapeia estes para os elementos recém-criados, mantendo a estrutura exata de conexão.

Overlays — os agrupamentos visuais que você cria para organizar diagramas complexos — são incluídos com suas posições, dimensões, cores e os elementos que contêm.

O que não é exportado atualmente: ADRs, documentação de projeto, fluxos de usuário e conexões de repositório. A exportação foca no modelo C4 em si — os sistemas, containers, componentes, código e seus relacionamentos. Estamos considerando expandir o escopo em releases futuras baseado no que os usuários nos dizem que precisam.

Sem Lock-In, Sem Truques

O formato de exportação usa a versão "1.0" hoje. Conforme adicionamos funcionalidades, atualizaremos o formato mantendo compatibilidade retroativa. Uma exportação que você criar hoje importará corretamente anos depois, mesmo conforme o Archyl evolui.

Não estamos interessados em prender seus dados. Estamos interessados em ser úteis o bastante para que você escolha ficar. Exportação e importação são nosso compromisso com essa filosofia. Se o Archyl parar de ser a ferramenta certa para você, leve sua arquitetura e vá. Se um concorrente construir algo melhor, facilitamos a troca. A pressão está em nós para continuar merecendo sua confiança.

Começando

Exportação e importação estão disponíveis em todos os planos, incluindo o Gratuito. Sem restrições artificiais, sem jogos de "exportação é uma funcionalidade premium".

Para exportar: abra qualquer projeto, encontre o botão de exportar, selecione JSON e salve o arquivo.

Para importar: da sua lista de projetos, clique em Importar, faça upload de um arquivo JSON, dê um nome ao seu novo projeto e confirme.

Sua documentação de arquitetura é sua. Agora você pode levá-la para qualquer lugar.

Quer aprender mais sobre o que você pode documentar no Archyl? Leia nossa Introdução ao Modelo C4 ou veja como a Descoberta de Arquitetura com IA pode mapear automaticamente seus sistemas existentes.