Conceitos Fundamentais
Esta página explica os conceitos-chave que você encontrará ao usar o Archyl.
Projetos
Um Projeto é o contêiner de nível superior para sua documentação de arquitetura. Cada projeto representa um sistema de software ou produto que você deseja documentar.
Projetos contêm:
- Diagramas de arquitetura (Sistemas, Contêineres, Componentes, Código)
- Relacionamentos entre elementos
- Documentação e ADRs
- Fluxos de usuário
- Configurações e acesso da equipe
Elementos
Elementos são os blocos de construção dos seus diagramas de arquitetura:
Sistemas
Um Sistema representa um sistema de software — o nível mais alto de abstração. No modelo C4, é isso que você está documentando.
- Sistemas Internos: Sistemas que você possui e mantém
- Sistemas Externos: Sistemas de terceiros com os quais você interage (APIs, produtos SaaS)
Contêineres
Um Contêiner é uma unidade implantável/executável separadamente que executa código ou armazena dados:
- Aplicações web
- Apps móveis
- Servidores API
- Bancos de dados
- Filas de mensagens
- Sistemas de arquivos
Componentes
Um Componente é um agrupamento de funcionalidades relacionadas dentro de um contêiner:
- Controladores
- Serviços
- Repositórios
- Módulos
Elementos de Código
Código representa o nível mais baixo — construções reais de código:
- Classes
- Interfaces
- Funções
- Módulos
Relacionamentos
Relacionamentos mostram como os elementos se comunicam ou dependem uns dos outros. Eles incluem:
- Um rótulo descrevendo a interação (ex: "Lê de", "Envia eventos para")
- Informação opcional de tecnologia (ex: "REST/HTTPS", "gRPC", "AMQP")
- Direção mostrando o fluxo
Sobreposições
Sobreposições são agrupamentos visuais que ajudam a organizar seus diagramas sem alterar a estrutura subjacente. Use-as para:
- Agrupar elementos relacionados
- Destacar áreas específicas
- Criar fronteiras visuais
Níveis
Archyl usa os quatro níveis de abstração do modelo C4:
| Nível | Mostra | Público |
|---|---|---|
| Contexto do Sistema | Seu sistema em seu ambiente | Todos |
| Contêiner | Blocos técnicos de alto nível | Pessoas técnicas |
| Componente | Estrutura de componentes dentro dos contêineres | Desenvolvedores |
| Código | Detalhes em nível de código | Desenvolvedores |
Organizações e Equipes
Organizações
Uma Organização é o workspace da sua conta. Ela contém:
- Todos os seus projetos
- Membros da equipe
- Informações de faturamento
- Configurações
Equipes
Equipes ajudam a organizar o acesso aos projetos:
- Agrupe membros da equipe por departamento, projeto ou responsabilidade
- Controle o acesso a projetos específicos
- Gerencie permissões no nível da equipe
Papéis
Archyl possui três papéis:
| Papel | Pode Visualizar | Pode Editar | Pode Administrar |
|---|---|---|---|
| Visualizador | Sim | Não | Não |
| Editor | Sim | Sim | Não |
| Administrador | Sim | Sim | Sim |
Descoberta com IA
Descoberta com IA é o processo de analisar automaticamente sua base de código para descobrir elementos de arquitetura. Ela:
- Conecta-se ao seu repositório Git
- Analisa a estrutura e padrões do código
- Identifica sistemas, contêineres e componentes
- Cria relacionamentos entre elementos
- Gera sugestões de documentação
ADRs
Registros de Decisão de Arquitetura (ADRs) documentam decisões importantes de arquitetura:
- O que foi decidido
- Por que foi decidido
- Quais alternativas foram consideradas
- Quais são as consequências
Fluxos
Fluxos de Usuário documentam como usuários ou dados se movem pelo seu sistema:
- Sequências passo a passo
- Links para elementos de arquitetura
- Diagramas de fluxo visuais