Como documentar soluções para decidir melhor, prever falhas e evoluir sem se perder

Franjola — Thu, 13 Aug 2026 23:40:15 +0000

Com esse roteiro, pretendo ajudar pessoas como eu, que sempre se perdem ao criar uma documentação de arquitetura, e, dessa forma, demonstrar que arquitetura, na realidade, é muito mais que C4.

Mas, pra falar a verdade, estou aprendendo muito mais tentando ensinar aqui pra vocês do que em qualquer pós que eu já fiz.

Para auxiliar no entendimento, vou usar um caso (mais ou menos) real e atual pra mim, que é um SaaS para integração e inteligência sobre plataformas de vendas.

E, assim, quero deixar bem claro: sou apenas um peixinho no oceano e estou aberta a qualquer crítica, sugestão ou correção!

Objetivo

Aprender a sair de uma ideia de produto e chegar a uma solução arquitetural que:

seja compreensível;
tenha decisões justificadas;
preveja falhas;
seja segura;
possa evoluir;
ajude a escolher tecnologias;
ajude a escolher infraestrutura/cloud;
permita medir se a solução está funcionando bem;
facilite manutenção, operação e evolução;
possa ser defendida tecnicamente em uma entrevista ou reunião de arquitetura.

Parte 1 — Entender o problema antes de desenhar a solução

Acho que essa parte é bem óbvia, mas, na realidade, não é tanto assim. É interessante entender exatamente qual problema vamos resolver com essa solução, quais dores ele causa no momento ou quais dores ela precisa sanar.

Abaixo, vou sempre responder às nossas dúvidas usando como exemplo o nosso negócio atual.

1. Visão do produto

Qual problema estamos resolvendo?

O cliente já possui sua operação de e-commerce na Nuvemshop, mas os dados gerados pela plataforma estão concentrados principalmente na operação da loja e nas vendas realizadas.

O problema que queremos resolver inicialmente é a dificuldade de transformar esses dados em uma visão mais clara sobre o desempenho comercial da loja, seus produtos e o comportamento das vendas.

Para quem?
Para lojistas com plataformas de vendas online que hoje estão “no escuro” em relação aos próprios dados e têm dificuldade de transformá-los em informações úteis para entender o desempenho do negócio e tomar decisões.
Qual valor o sistema entrega?
Transformar os dados que o lojista já possui em informações mais claras e úteis para a tomada de decisão.

A ideia é permitir que ele consiga entender melhor o desempenho da loja, identificar quais produtos possuem maior relevância para o faturamento, acompanhar vendas, ticket médio, estoque e outros indicadores sem precisar analisar manualmente os dados da operação.

O que é MVP?
MVP (Minimum Viable Product ou Produto Mínimo Viável) é a primeira versão do produto que possui o mínimo necessário para resolver o problema principal e validar se a solução realmente gera valor para o cliente.
O que explicitamente não faz parte do MVP?
Tudo aquilo que pode gerar valor no futuro, mas que não é necessário para validar o problema inicial.

Por exemplo: integração com múltiplos canais de venda, redes sociais, marketplaces, previsões de demanda, recomendações personalizadas, segmentação automática de clientes e outras funcionalidades avançadas de ciência de dados.

2. Stakeholders e usuários

Antes de pensar na solução, precisamos entender quem são as pessoas, grupos ou sistemas que possuem algum interesse ou participação nela. Nem todo stakeholder necessariamente utiliza o sistema diretamente, mas pode afetá-lo ou ser afetado por ele.

No nosso exemplo:

Usuário final

É quem efetivamente utilizará a solução no dia a dia. Neste momento, podemos considerar como usuário final o lojista ou funcionário da loja que utilizará o dashboard para acompanhar vendas, produtos, estoque e indicadores.

Cliente

É a empresa ou lojista que contrata o DressCode e possui sua operação de vendas em alguma plataforma de e-commerce.

Administradores

São usuários do cliente com permissões administrativas dentro da solução. Podem, por exemplo, gerenciar outros usuários da loja, realizar configurações e exportar dados.

Sistemas externos

No exemplo, o principal sistema externo é a Nuvemshop, que continua sendo a fonte operacional de produtos, categorias, estoque, pedidos e pagamentos.

3. Jornadas e fluxos principais

Aqui começamos a entender como o negócio funciona na prática, ainda sem pensar em tecnologia ou em como vamos implementar a solução.
A ideia é mapear o caminho esperado, o que pode acontecer de diferente, quais fluxos não podem falhar sem causar impacto relevante e de quais sistemas externos dependemos.

Na prática vamos mapear o caminho perfeito e prever quais pedras podemos encontrar no caminho.

Happy path Considerando nossa plataforma de exemplo

Cliente possui sua loja na Nuvemshop/provedor
        ↓
A loja realiza vendas normalmente
        ↓
Os dados da operação são disponibilizados
        ↓
Nossa plataforma obtém esses dados
        ↓
Os dados são organizados e analisados
        ↓
O lojista acessa o dashboard
        ↓
Visualiza indicadores sobre seu negócio

Fluxos alternativos É como se você tivesse traçado uma rota antes de sair de casa para o estabelecimento x, porém o WAZE resolveu te jogar em outra rota. Em palavras menos neurodivergentes, o seu objetivo continua podendo ser alcançado, mas o caminho não acontece como no cenário principal.

Não existem vendas no período selecionado
→ dashboard precisa representar corretamente a ausência de dados

Produto não possui vendas
→ ainda pode ser relevante apresentar informações sobre estoque

Cliente acabou de conectar sua loja
→ ainda não temos histórico suficiente para determinadas análises

Dados ainda não foram completamente atualizados
→ algumas informações podem estar temporariamente defasadas

Perceba que não estamos analisando nesse momento como vamos resolver, estamos só analisando quais situações podem ocorrer.

Fluxos críticos

São as situações que vão fazer a gente virar a madrugada com vontade de chorar, são fluxos cujo funcionamento incorreto pode comprometer diretamente o valor que estamos entregando.

A loja vende R$ 10.000 na Nuvemshop
              ↓
A aplicação obtém essas vendas
              ↓
As vendas são armazenadas corretamente
              ↓
Os indicadores são calculados
              ↓
O dashboard apresenta:
Faturamento de hoje = R$ 10.000

Esse é um fluxo crítico porque uma falha em qualquer uma dessas etapas pode fazer com que o SaaS entregue uma informação incorreta.

Um exemplo ainda mais grave seria, no futuro, quando tivermos mais de uma loja, entregarmos indicadores da Loja A para a Loja B. Essa seria uma falha gravíssima, pois, além de apresentarmos informações incorretas, estaríamos expondo os dados de um cliente para outro.

Dependências externas Aqui identificamos tudo aquilo de que nossa solução depende, mas que não controlamos.

No cenário atual, a principal dependência externa é a Nuvemshop. Ela é a fonte operacional de produtos, categorias, estoque, pedidos e pagamentos no desenho atual.

Isso imediatamente levanta perguntas importantes:

E se a Nuvemshop ficar indisponível?
E se responder lentamente?
E se limitar a quantidade de consultas?
E se alterar sua API?
E se nossa autorização for revogada?
E se recebermos dados atrasados?
E se deixarmos de receber alguma atualização?

Entenda que não precisamos responder tudo agora, mas precisamos identificar quais erros podemos sofrer.

Nesse momento precisamos entender como entregar valor e posteriormente vamos responder como nossa arquitetura fará isso acontecer.

4. AS IS
A expressão "as is" significa literalmente "como está" em inglês, o que deixa bem claro o que é necessário mapear, como o negócio funciona agora, sem nossa solução.

Como o processo funciona hoje? A loja utiliza a Nuvemshop para sua operação de e-commerce. Produtos, estoque, pedidos e pagamentos são gerenciados pela plataforma.

Para acompanhar o desempenho do negócio, o lojista depende das informações disponibilizadas pelo provedor de dados coletados manualmente, como estoque e métricas de acesso às redes sociais. Essas informações ficam dispersas em diferentes fontes, dificultando uma visão consolidada e clara de como a loja está performando.

Quais sistemas já existem?

No cenário atual que conhecemos, temos principalmente:

Loja
  ↓
Nuvemshop
  ├── Produtos
  ├── Estoque
  ├── Pedidos
  └── Pagamentos

Quais limitações existem?
Atualmente, o cliente possui acesso a poucos dados disponibilizados pelo provedor e também coleta manualmente algumas informações de suas redes sociais. Com isso, esses dados ficam dispersos em diferentes fontes, sem a possibilidade de unificá-los para gerar informações mais produtivas e relevantes para a tomada de decisão.
Onde estão os gargalos?
Para identificar gargalos, precisamos observar onde o processo atual gera esforço, demora, dependência, retrabalho ou dificuldade para alcançar o resultado esperado.

Algumas perguntas ajudam nessa identificação:

Quais atividades ainda são realizadas manualmente?
Onde o cliente gasta mais tempo?
Quais informações precisam ser buscadas em diferentes lugares?
Existem dados que não conseguimos relacionar entre si?
O cliente depende das limitações de alguma plataforma?
Existe retrabalho para obter ou analisar informações?
Quais informações seriam importantes para uma decisão, mas hoje são difíceis de obter?

No nosso exemplo, identificamos como principais gargalos:

coleta manual de parte das informações;
dados dispersos entre a plataforma de vendas e redes sociais;
dificuldade para unificar e cruzar esses dados;
ausência de uma visão centralizada do negócio;
maior esforço para transformar os dados existentes em informações úteis para tomada de decisão.

5. TO BE
Essa é a parte bacana, como a aplicação será no futuro, o que estamos propondo como solução.
Se no AS IS entendemos onde estamos e quais são os gargalos atuais, aqui começamos a definir onde queremos chegar, ainda sem precisar decidir todos os detalhes técnicos da solução.

Qual é a visão futura? No nosso exemplo, queremos que o lojista consiga ter uma visão mais completa da sua operação, reunindo dados de vendas, produtos, estoque e, futuramente, outros canais, permitindo cruzar essas informações e transformá-las em indicadores úteis para a tomada de decisão.

De forma simplificada:

HOJE
Nuvemshop ───────→ dados
Instagram ───────→ dados       → análises separadas
Outras fontes ───→ dados

FUTURO
Nuvemshop ──────┐
Redes sociais ──┼──→ plataforma ──→ dados consolidados
Outros canais ──┘                       ↓
                                  indicadores
                                       ↓
                                    insights
                                       ↓
                                    decisões

O que queremos permitir depois? Aqui entram funcionalidades que fazem sentido para a evolução do produto, mas não são necessárias para validar o MVP.

No nosso exemplo:

integração com redes sociais;
integração com marketplaces;
novos canais de venda;
comparação e correlação entre dados de diferentes fontes;
segmentação de clientes;
recomendações;
previsão de demanda;
análises e recursos de ciência de dados.
O que deve estar preparado desde o início?
Essa pergunta é muito importante porque “estar preparado” não significa “construir agora”.

Precisamos identificar decisões que, se forem tomadas de maneira errada hoje, podem tornar a evolução futura muito cara.

No nosso exemplo, sabemos que começaremos com uma loja e um provedor, mas queremos que futuramente existam várias lojas e diferentes fontes de dados.

Por isso, faz sentido preparar desde o início conceitos como:

tenant
→ quem é o cliente/loja?
provider
→ de onde o dado veio?
channel
→ por qual canal aquela informação/venda aconteceu?

Arquitetura preparada para:

Cliente A
 ├── Nuvemshop
 ├── Instagram
 └── Marketplace

Cliente B
 ├── Nuvemshop
 ├── Instagram
 └── Marketplace

O que não devemos antecipar? Tudo aquilo que pertence à visão futura, mas ainda não resolve um problema necessário para o MVP.

Por exemplo, não precisamos construir agora:

integração completa com vários provedores que ainda não temos;
infraestrutura para milhões de usuários sem existir essa demanda;
microsserviços apenas porque futuramente o sistema pode crescer;
modelos avançados de Machine Learning sem volume de dados suficiente;
mecanismos complexos de escalabilidade antes de conhecer a carga real;
abstrações genéricas para todos os possíveis cenários futuros.

Uma boa pergunta para decidir se algo precisa ser antecipado é:

Se eu não fizer isso agora, será muito caro mudar depois?
Se sim, talvez seja necessário preparar a arquitetura.
Se não, provavelmente podemos esperar.

A ideia do TO BE não é construir o futuro hoje. É saber para onde queremos ir para evitar decisões no presente que bloqueiem esse futuro.

Nos próximos posts vamos falar sobre:

Parte 2 — Requisitos
Parte 3 — Modelagem do domínio
Parte 4 — Arquitetura lógica
Parte 5 — Decisões arquiteturais
Parte 6 — Autenticação, autorização e isolamento
Parte 7 — Integrações externas
Parte 8 — Resiliência e falhas
Parte 9 — Observabilidade
Parte 10 — Segurança
Parte 11 — Infraestrutura
Parte 12 — Escolha de ferramentas
Parte 13 — DevOps e entrega
Parte 14 — Dados e recuperação
Parte 15 — Performance e capacidade
Parte 16 — Custos
Parte 17 — Operação
Parte 18 — Evolução da arquitetura
Parte 19 — Pacote final de arquitetura
Parte 20 — A pergunta que deve acompanhar toda decisão

DEV Community: Franjola

Como documentar soluções para decidir melhor, prever falhas e evoluir sem se perder