Criando Seu Primeiro Projeto - Archyl Docs

Um guia passo a passo para criar e documentar seu primeiro projeto de arquitetura no Archyl

Criando Seu Primeiro Projeto

Este guia completo orienta você na criação do seu primeiro projeto de documentação de arquitetura no Archyl, desde a configuração inicial até o compartilhamento com sua equipe.

Pré-requisitos

Antes de começar:

  • Uma conta no Archyl (cadastre-se aqui)
  • Um sistema de software que você deseja documentar
  • Opcionalmente: Acesso ao repositório da sua base de código

Passo 1: Criar um Novo Projeto

A Partir do Painel

  1. Faça login no Archyl
  2. Clique no botão "+ Novo Projeto"
  3. Insira os detalhes do projeto:
    • Nome: Um nome claro e descritivo (ex: "Plataforma E-commerce")
    • Descrição: Visão geral breve do sistema
    • Tags: Palavras-chave para organização (ex: "backend", "microsserviços")
  4. Clique em "Criar Projeto"

Configurações do Projeto

Após a criação, configure seu projeto:

  • Visibilidade: Público ou privado
  • Acesso da equipe: Quais equipes podem visualizar/editar
  • Repositório: Conecte para descoberta com IA (opcional)

Passo 2: Entender o Contexto do Sistema

Antes de desenhar diagramas, entenda o contexto do seu sistema:

Identificar Usuários

Quem usa seu sistema?

  • Usuários finais (clientes, funcionários)
  • Administradores
  • Desenvolvedores externos
  • Outros sistemas

Identificar Sistemas Externos

Com o que seu sistema interage?

  • Processadores de pagamento
  • Provedores de autenticação
  • Serviços de email/notificação
  • Plataformas de analytics
  • APIs de parceiros

Passo 3: Criar o Diagrama de Contexto do Sistema

Adicionar Seu Sistema Principal

  1. No canvas vazio, clique em "+" ou clique com o botão direito
  2. Selecione "Adicionar Sistema"
  3. Insira:
    • Nome: O nome do seu sistema
    • Descrição: O que ele faz
    • Tipo: Interno (você é o proprietário)

Adicionar Usuários

  1. Clique em "+" e selecione "Adicionar Pessoa"
  2. Crie cada tipo de usuário:
    • Nome: "Cliente", "Usuário Admin", etc.
    • Descrição: Seu papel e o que fazem

Adicionar Sistemas Externos

  1. Clique em "+" e selecione "Adicionar Sistema Externo"
  2. Para cada dependência externa:
    • Nome: "Stripe", "SendGrid", etc.
    • Descrição: O que fornece

Criar Relacionamentos

  1. Passe o mouse sobre o elemento de origem
  2. Arraste do ponto de conexão até o destino
  3. Adicione um rótulo: "Faz pedidos via", "Envia emails através de", etc.
  4. Opcionalmente adicione tecnologia: "REST/HTTPS", "SMTP"

Passo 4: Aprofundar nos Contêineres

Abrir a Visão de Contêineres

Clique duas vezes no seu sistema principal para ampliar para o nível de Contêiner.

Identificar Contêineres

Quais são os blocos técnicos de construção?

  • Aplicações: App web, app móvel, cliente desktop
  • Serviços: Servidor API, workers em segundo plano
  • Armazenamento de dados: Bancos de dados, caches, armazenamento de arquivos
  • Filas de mensagens: Barramentos de eventos, filas

Adicionar Contêineres

Para cada contêiner:

  1. Clique em "+" e selecione "Adicionar Contêiner"
  2. Insira:
    • Nome: "Aplicação Web", "Servidor API", "PostgreSQL"
    • Descrição: Sua responsabilidade
    • Tecnologia: "React", "Node.js", "PostgreSQL 15"

Conectar Contêineres

Mostre como os contêineres se comunicam:

  • App Web → Servidor API: "Faz chamadas API [REST/HTTPS]"
  • Servidor API → Banco de Dados: "Lê/escreve dados [SQL]"
  • Servidor API → Cache: "Armazena dados de sessão [protocolo Redis]"

Passo 5: Adicionar Componentes (Opcional)

Para contêineres críticos, aprofunde nos componentes:

  1. Clique duas vezes em um contêiner
  2. Adicione componentes representando os módulos principais:
    • Controllers
    • Serviços
    • Repositórios
    • Utilitários

Passo 6: Usar a Descoberta com IA (Opcional)

Deixe a IA ajudar a documentar sua arquitetura:

Conectar Repositório

  1. Vá para Configurações do Projeto → Repositório
  2. Conecte seu provedor Git
  3. Selecione seu repositório

Executar Descoberta

  1. Clique em "Iniciar Descoberta"
  2. Aguarde a análise ser concluída
  3. Revise as descobertas pendentes

Revisar e Aprovar

  1. Verifique cada elemento descoberto
  2. Edite nomes/descrições se necessário
  3. Aprove itens precisos
  4. Rejeite ou modifique itens incorretos

Passo 7: Adicionar Documentação

Descrições dos Elementos

Clique em qualquer elemento e adicione descrições detalhadas:

  • Propósito e responsabilidades
  • Decisões-chave tomadas
  • Notas importantes

Registros de Decisão de Arquitetura

Documente decisões importantes:

  1. Vá para a seção ADRs
  2. Clique em "Novo ADR"
  3. Preencha:
    • Título: "Usar PostgreSQL para persistência"
    • Contexto: Por que essa decisão foi necessária
    • Decisão: O que foi decidido
    • Consequências: Impacto da decisão

Vincular Documentação

Vincule ADRs e documentos a elementos específicos para contexto.

Passo 8: Compartilhar com Sua Equipe

Convidar Membros da Equipe

  1. Vá para Configurações do Projeto → Equipe
  2. Clique em "Convidar"
  3. Insira endereços de email
  4. Atribua papéis (Visualizador, Editor, Administrador)

Criar Links de Compartilhamento

Para stakeholders sem conta:

  1. Clique em "Compartilhar" na barra de ferramentas
  2. Configure as opções de acesso
  3. Copie e compartilhe o link

Exportar Diagramas

Para apresentações ou documentos:

  1. Clique em "Exportar"
  2. Escolha o formato (PNG, SVG, PDF)
  3. Baixe seus diagramas

Boas Práticas

Comece Simples

  • Comece com o Contexto do Sistema
  • Adicione detalhes progressivamente
  • Não tente documentar tudo de uma vez

Mantenha Atualizado

  • Atualize quando a arquitetura mudar
  • Execute a descoberta com IA após mudanças significativas
  • Revise regularmente com sua equipe

Foque na Comunicação

  • Use nomes claros e descritivos
  • Adicione contexto nas descrições
  • Mostre os relacionamentos mais importantes

Próximos Passos

Parabéns! Você criou sua primeira documentação de arquitetura. Continue aprendendo: