Arquitetura¶
As páginas desta seção descrevem a arquitetura implementada do backend.
| Visão | Pergunta respondida |
|---|---|
| Lógica — C4 contexto e containers | Quais são as fronteiras e responsabilidades implementadas? |
| Infraestrutura por ambiente | O que é corporativo, ambiente local ou experimento? |
| Referência cloud | O que o desenho do arquiteto propõe e o que ainda não foi comprovado? |
| Control Plane — integrações administrativas | Quais destinos o BFF consome e qual seu papel na administração? |
| Dependências e integrações | Quem consome quem, para quê e por qual mecanismo nos 23 serviços backend? |
| BFF — componentes C4 e ficha piloto | Como a entrada administrativa está implementada? |
As relações entre serviços são lógicas e não definem namespaces, réplicas ou políticas de rede. O Control Plane administra configurações e o Data Plane processa requisições; essa separação não implica isolamento físico.
Modelagem de dados reúne collections, revisões, caches e diagramas de persistência por domínio.
Convenção C4¶
Usamos C4 como referência de níveis e fronteiras, com Mermaid flowchart para os desenhos versionáveis. Contexto mostra pessoas e sistemas; containers mostra aplicações e armazenamentos executáveis; componentes detalha responsabilidades internas de um único container, inicialmente o BFF. Container C4 não significa necessariamente container Docker.
Cada nó identifica tipo e, quando pertinente, tecnologia. Setas indicam direção da chamada/uso e protocolo ou finalidade. Subgraphs funcionais não afirmam isolamento de rede. O desenho cloud é identificado como referência; suas relações não comprovadas são pontilhadas. Sequências representam interações específicas e não substituem fluxos E2E completos.
Cada diagrama responde a uma pergunta. Visões densas são divididas em recortes de entrada, domínio, segurança e dados; relações complementares ficam nas tabelas. Evitar rolagem horizontal em desktop e manter texto renderizado de pelo menos 14 px. No celular, preservar a legibilidade com rolagem local quando necessária.
Retângulos representam serviços ou grupos nomeados; cilindros, armazenamento; caixas com bordas duplas, mensageria; formas arredondadas, sistemas externos. As setas indicam chamadas ou transporte de dados, conforme o rótulo.
As classes Mermaid entry, domain, security, store, async e external usam a mesma paleta adaptada aos temas claro e escuro. Os rótulos e formatos reforçam as cores. Setas tracejadas indicam relações propostas no desenho cloud; agrupamentos lógicos não definem deployment.
Em sequências, os participantes são componentes/serviços e usam a cor de processamento; suas responsabilidades são identificadas pelos nomes. Nomes abreviados são explicados no texto. Não reduzir diagramas complexos até tornar seus rótulos ilegíveis.
Hierarquia dos componentes¶
Nomes usam 17 px e peso 600; descrições usam 15 px, peso normal e cor secundária adaptada ao tema, com contraste mínimo de 4,5:1. O conteúdo é centralizado, com separação de 4 px entre nome e descrição e padding de 14 px no componente. Títulos de grupos e rótulos de conexões mantêm seu estilo próprio. Participantes de sequências usam o mesmo destaque dos nomes, sem alterar o texto das mensagens.
Nos flowcharts, escreva o nome e uma descrição curta com <br/><small>…</small>, por exemplo: core["Core<br/><small>Gateways e rotas</small>"]:::domain. Quebras adicionais podem ficar dentro de <small>. Componentes sem descrição recebem apenas o nome; não é necessário inventar uma responsabilidade para preencher o desenho.
hooks/mermaid.json habilita labels HTML nativas do Mermaid. assets/stylesheets/mermaid.css centraliza a tipografia dentro dos SVGs, e documentation.css define as cores de cada tema. Não adicionar estilos inline ou estruturas HTML complexas aos diagramas. Validar as dimensões e o contraste dos dois níveis de texto após alterar labels.
Referências de notação: C4 — diagramas e Mermaid no Material. Optou-se pela sintaxe flowchart para manter os níveis C4 sem depender da sintaxe experimental C4 do Mermaid.
Leitura das evidências¶
Toda afirmação implementada deve remeter a código, contrato, configuração ou teste no commit indicado. O registro de evidências define os limites. Análises registram riscos e recomendações separadamente do comportamento descrito aqui.