> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/all-id/architecture-overview.md). # Visão Geral da Arquitetura Como o All ID funciona e como os componentes interagem. ## Arquitetura do sistema ``` ┌─────────────┐ │ Cliente │ └──────┬──────┘ │ HTTPS ┌──────▼──────────┐ │ Balanceador de carga │ └──────┬──────────┘ │ HTTP:1302 ┌──────▼──────────┐ ┌────────────────┐ │ Serviço Peer │──────▶│ Facematch │ │ • Orquestra │HTTP │ • Correspondência facial │ │ • Expõe API │:8080 │ • Anonimiza │ │ • Armazena dados │ │ • Extrai │ └──────┬──────────┘ └────────────────┘ │ MySQL:3306 ┌──────▼──────────┐ │ Banco de dados MySQL │ │ • Perfis │ │ • Identificadores │ │ • Transações │ └─────────────────┘ ``` ## Serviço Peer O Serviço Peer é o componente principal da aplicação. **O que ele faz**: * Expõe `REST` `API` endpoints (`/profiles`, `/profiles/biometric-validation`) * Valida requisições recebidas * Orquestra operações biométricas * Armazena e recupera dados do MySQL * Chama o Serviço Facematch para reconhecimento facial * Pode se comunicar com o Serviço de Roteamento da Certta para operações distribuídas * Retorna respostas aos clientes **Tecnologia**: aplicação Node.js **Requer**: Serviço Facematch, Banco de dados MySQL ## Serviço Facematch O Serviço Facematch lida com operações de reconhecimento facial. **O que ele faz**: * Recebe imagens biométricas do Peer * Extrai características faciais usando modelos de ML * Calcula pontuações de similaridade entre rostos * Anonimiza imagens biométricas * Retorna vetores de características e pontuações para o Peer **Tecnologia**: serviço de aprendizado de máquina com modelos incorporados **Requer**: Nenhuma (autocontido, modelos incluídos na imagem) ## Serviço de Roteamento (hospedado pela Certta) O Serviço de Roteamento é um componente de orquestração hospedado e gerenciado pela Certta (não implantado por você). **O que ele faz**: * Roteia consultas biométricas entre múltiplas instâncias Peer de clientes * Permite buscas de perfis distribuídas entre regiões * Coordena operações entre instâncias para implantações multirregião **Comunicação**: * Seu Peer → Roteador da Certta: solicitações HTTP para consultas distribuídas * Roteador da Certta → Seu Peer: callbacks HTTP com resultados **Quando usado**: implantações multirregião em que os dados de perfil são distribuídos entre locais geográficos {% hint style="info" %} Você não implanta nem gerencia o Serviço de Roteamento. Ele roda na infraestrutura da Certta e seu Serviço Peer se conecta a ele quando necessário para operações distribuídas. {% endhint %} ## Banco de dados MySQL Armazenamento persistente para todos os dados biométricos. **O que armazena**: * Perfis biométricos (características faciais, metadados) * Identificadores de usuário (CPF, nome etc.) * Histórico de transações * Resultados de validação **Tecnologia**: MySQL 8.0+ ou Aurora MySQL 3.10.0+ **Esquema**: Fornecido pela Certta durante a configuração ## Fluxos de dados ### Fluxo de criação de perfil ``` 1. Cliente → POST /profiles → Serviço Peer 2. O Peer valida o esquema da requisição 3. O Peer armazena identificadores → Banco de dados 4. O Peer envia a imagem biométrica → Facematch 5. O Facematch extrai características, anonimiza-as (gira a embedding com uma matriz de rotação privada por Peer), e retorna o vetor de embedding rotacionado 6. O Peer armazena o vetor de embedding rotacionado → Banco de dados 7. O Peer retorna sucesso → Cliente ``` **O que é persistido no banco de dados**: * **Vetor de embedding** (bytes) — o vetor de características rotacionado e anonimizado. A imagem bruta nunca é armazenada. * **Metadados do mecanismo** — versão do modelo e hash da imagem usados para gerar o embedding. * **Metadados de perfil/ativo** — identificadores e outros dados no nível do perfil. A anonimização (rotação) acontece dentro do Facematch antes de o vetor ser retornado, então o Peer só lida e persiste dados já anonimizados. ### Fluxo de validação biométrica ``` 1. Cliente → POST /profiles/biometric-validation → Serviço Peer 2. O Peer valida o esquema da requisição 3. O Peer consulta o perfil existente → Banco de dados 4. O Peer envia a solicitação de comparação → Facematch 5. O Facematch calcula a pontuação de similaridade 6. O Facematch retorna a pontuação e a confiança → Peer 7. O Peer aplica a lógica de limiar (MATCH/NO_MATCH) 8. O Peer armazena a transação → Banco de dados 9. O Peer retorna o resultado da validação → Cliente ``` ### Fluxo de validação distribuída (com o Roteador da Certta) ``` 1. Cliente → Solicitação de validação → Seu Peer (Região A) 2. Seu Peer verifica o banco de dados local 3. Perfil não encontrado localmente 4. Seu Peer consulta → Serviço de Roteamento da Certta 5. O Roteador da Certta identifica a região de destino 6. O Roteador da Certta encaminha → Outro Peer (Região B) 7. O Peer B realiza a validação 8. O Peer B retorna o resultado → Roteador da Certta → Seu Peer → Cliente ``` **Rotação de embedding entre peers**: Cada peer possui sua própria matriz de rotação ortogonal privada, então um embedding anonimizado para um peer não é diretamente comparável com os dados de outro peer. Quando uma consulta cruza limites entre peers, o Roteador re-rota o embedding — revertendo a rotação do peer solicitante e reaplicando a rotação do peer que responde — antes de encaminhá-lo para comparação. Isso permite que instâncias Peer comparem dados biométricos pela rede sem que qualquer peer veja a matriz de rotação privada de outro peer ou um embedding sem rotação. {% hint style="info" %} O Serviço de Roteamento é hospedado pela Certta. Você só precisa configurar seu Serviço Peer para se conectar ao endpoint do Roteador da Certta. {% endhint %} ## Descoberta de serviços Seus serviços se localizam usando DNS: ``` peer.biometrics.internal:1302 facematch.biometrics.internal:8080 database.biometrics.internal:3306 ``` Configure por meio de variáveis de ambiente (`FACEMATCH_IP`, `MYSQL_IP`, etc.) Para implantações distribuídas, configure o endpoint do Roteador da Certta (fornecido pela Certta) em `DS_IP` e `DS_PORT` variáveis. ## Estratégia de escalonamento **Escalonamento horizontal** (recomendado): * Adicione mais instâncias Peer → processe mais solicitações de API * Adicione mais instâncias Facematch → processe mais correspondências em paralelo * Use réplicas de leitura do banco de dados → atenda mais consultas de leitura **Escalonamento vertical**: * Aumente os recursos do Peer → processamento de requisições mais rápido * Aumente os recursos do Facematch → correspondência mais rápida (benefício limitado, preferencialmente horizontal) * Aumente os recursos do banco de dados → processamento de consultas mais rápido ## Alta disponibilidade **Implantação com múltiplas instâncias**: * Implante 2+ instâncias Peer atrás do balanceador de carga * Implante 2+ instâncias Facematch * Use banco de dados Multi-AZ **Verificações de integridade**: * Peer: `GET /health` na porta 1302 * Facematch: `GET /health` na porta 8080 * Banco de dados: ping do MySQL **Failover automático**: * O balanceador de carga remove instâncias Peer com problemas * O Peer descobre instâncias Facematch saudáveis via DNS * O banco de dados faz failover para o standby (Multi-AZ) ## Arquitetura de segurança **Camadas de rede**: ``` Camada pública → Balanceador de carga (HTTPS) Camada privada → Peer, Facematch Camada de banco de dados → MySQL (isolado) ``` **Autenticação**: * Cliente → Balanceador de carga: implemente autenticação (chaves de API, OAuth2 etc.) * Serviços: comuniquem-se na rede privada sem autenticação **Criptografia**: * Tráfego do cliente: HTTPS (TLS) * Conexões com o banco de dados: TLS ativado * Dados em repouso: criptografia do banco de dados ativada --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/all-id/architecture-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.