Nossos diagramas de arquitetura pareciam perfeitos. Entao um relatorio de bug chegou, e percebemos que ninguem realmente entendia como um usuario se movia pelo sistema. Eis como corrigimos isso.

Documentando Fluxos de Usuario na Sua Arquitetura de Software

O relatorio de bug parecia simples: "Checkout falha intermitentemente."

Tinhamos diagramas de arquitetura lindos. Diagramas C4 mostrando cada servico, cada banco de dados, cada integracao. Mas quando tentamos rastrear a jornada de um usuario de "adicionar ao carrinho" ate "pedido confirmado", ninguem conseguia concordar na sequencia exata. Quais servicos estavam envolvidos? Em que ordem? Onde a verificacao de estoque acontecia — antes ou depois do pagamento?

Tres engenheiros tinham tres modelos mentais diferentes. Nossos diagramas de arquitetura estaticos mostravam a estrutura, mas nao o comportamento. Podiamos ver as caixas e setas, mas nao podiamos ver como um usuario realmente se movia pelo sistema.

Foi quando percebi que precisavamos de fluxos de usuario.

O Que Sao Fluxos de Usuario

Um fluxo de usuario documenta a jornada que um usuario faz pelo seu sistema para realizar um objetivo. Nao a estrutura estatica (para isso servem os diagramas C4), mas a sequencia dinamica.

A Lacuna Entre Estrutura e Comportamento

Um diagrama de containers C4 diz quais componentes existem e como se conectam. Mas nao responde: Quando um usuario faz checkout, o que acontece primeiro? A API valida o estoque antes de chamar o pagamento? O que acontece se o pagamento e aprovado mas o estoque agora esta indisponivel?

Essas perguntas requerem entender o fluxo, nao apenas a estrutura.

Anatomia de um Fluxo de Usuario Util

1. Declaracao de Objetivo

Comece com o que o usuario esta tentando realizar.

2. Pre-condicoes

O que deve ser verdade antes que este fluxo comece?

3. O Caminho Feliz

Documente o caminho de sucesso esperado primeiro, incluindo o que o usuario faz E como o sistema responde.

4. Caminhos de Erro e Casos Extremos

O caminho feliz e apenas o comeco. O valor real vem de documentar o que acontece quando as coisas dao errado.

5. Notas Tecnicas

Adicione qualquer contexto tecnico relevante.

Conectando Fluxos a Arquitetura

No Archyl, podemos anotar quais componentes estao envolvidos em cada etapa de um fluxo. Isso cria rastreabilidade bidirecional:

Olhando um fluxo? Veja quais componentes ele toca.
Olhando um componente? Veja quais fluxos passam por ele.

Diferentes Tipos de Fluxos

Fluxos de Usuario

Sequencias iniciadas pelo usuario a partir da UI.

Fluxos de Sistema

Sequencias iniciadas por maquina.

Fluxos de Integracao

Sequencias entre sistemas.

Erros Comuns

Erro 1: Muito Detalhe

Um documento de fluxo nao deveria ler como codigo.

Erro 2: Documentar Apenas Caminhos Felizes

Os caminhos de erro sao onde os bugs vivem.

Erro 3: Nao Atualizar Apos Mudancas

Um fluxo documentado que nao corresponde a realidade e pior do que nenhuma documentacao.

Erro 4: Tratar Fluxos Como Estaticos

Fluxos de usuario evoluem. Trate-os como documentos vivos.

Conclusao

Diagramas de arquitetura estaticos dizem do que seu sistema e feito. Fluxos de usuario dizem como ele se comporta. Voce precisa de ambos.

Na proxima vez que estiver debugando um problema complexo entre multiplos servicos, pergunte-se: "Temos um fluxo documentado para isso?" Se a resposta for nao, voce passara horas reconstruindo como as pecas se encaixam.

Comece com seu fluxo mais critico. Para a maioria dos sistemas, provavelmente e autenticacao ou o caminho de conversao principal.

Mais sobre documentacao de arquitetura: Introducao ao Modelo C4 | Registros de Decisao de Arquitetura | Por Que a Documentacao Importa

Documentando Fluxos de Usuario na Sua Arquitetura de Software - Archyl Blog