Este documento apresenta a arquitetura da solução RetinaScan com foco nos componentes de implantação e no fluxo de processamento das inferências.
O escopo cobre:
- visão lógica da solução e comunicação entre componentes;
- visão de processos para execução das inferências;
- visão de implementação baseada na estrutura de diretórios do projeto;
- visão de implantação da infraestrutura em produção;
- visão de dados e persistência, substituindo a visão de casos de uso.
O documento está organizado segundo o modelo 4+1 adaptado para o contexto do projeto: visão lógica, visão de processos, visão de implementação, visão de implantação e visão de dados.
- API: Interface de Programação de Aplicações.
- HTTPS: protocolo seguro de comunicação HTTP.
- VPS: servidor privado virtual.
- IA: Inteligência Artificial.
- Broker: serviço intermediário de mensageria para filas.
A visão lógica descreve os componentes principais da solução e seus papéis funcionais.
A arquitetura está organizada em uma VPS com Docker Swarm e rede overlay, contendo os seguintes componentes:
- Cliente: consome a aplicação via HTTPS.
- Nginx: atua como proxy reverso nas portas 443/80.
- Backend Node (core): centraliza gestão de usuários e orquestração principal.
- Backend FastAPI: executa o domínio de inferência.
- Redis: broker de tarefas assíncronas.
- Celery Worker: processamento de inferência com modelo PyTorch.
- PostgreSQL: persistência relacional dos dados de domínio.
- MinIO: armazenamento de objetos para imagens e artefatos.
| Tecnologia | Papel na arquitetura |
|---|---|
| Nginx | Entrada única da aplicação e roteamento reverso |
| Node.js | Backend central de regras de negócio e usuários |
| FastAPI | Serviço especializado de inferência |
| Redis | Fila e intermediação de tarefas assíncronas |
| Celery | Execução de jobs de inferência em segundo plano |
| PyTorch | Runtime do modelo de IA |
| PostgreSQL | Banco relacional transacional |
| MinIO | Armazenamento de imagens e arquivos |
| Docker Swarm | Orquestração dos serviços na VPS |
- Todas as entradas externas devem passar pelo Nginx com HTTPS.
- O processamento de inferência deve ser assíncrono para evitar bloqueio de API.
- O backend principal deve permanecer desacoplado do runtime do modelo.
- Dados transacionais devem permanecer em banco relacional.
- Arquivos de imagem devem ser armazenados em serviço de objetos dedicado.
- A solução deve permitir evolução modular por serviço.
A visão de processos descreve o fluxo operacional entre serviços e filas de execução.
- O cliente envia requisições HTTPS para o Nginx.
- O Nginx direciona chamadas para o Backend Node.
- O Backend Node executa regras de negócio e persiste dados no PostgreSQL.
- Para inferência, o Backend Node aciona o Backend FastAPI.
- O FastAPI publica tarefas no Redis para processamento assíncrono.
- O Celery Worker consome a fila, executa o modelo PyTorch e devolve resultado.
- Metadados são gravados no PostgreSQL e arquivos no MinIO.
A visão de implementação descreve a organização interna do código e suas camadas.
A implementação segue a estrutura abaixo:
env
src
|- api
| |- controllers
| |- middlewares
| |- routes
|- infra
| |- container
| |- database
| |- storage
|- modules
| |- users
| |- domain
| |- repositories
| |- use-cases
|- tests
|- integration
|- unit
Responsável pela borda HTTP da aplicação:
- controllers: recebem requisições e orquestram casos de uso.
- middlewares: aplicam autenticação, autorização e validações transversais.
- routes: definem endpoints e composição de rotas.
Responsável por detalhes técnicos de infraestrutura:
- container: configuração de execução e empacotamento.
- database: conexão e acesso ao PostgreSQL.
- storage: integração com MinIO.
Responsável pelo domínio de negócio, com separação por contexto:
- domain: entidades, regras e contratos.
- repositories: persistência orientada ao domínio.
- use-cases: casos de uso e orquestração da lógica de aplicação.
- unit: valida regras isoladas de domínio e aplicação.
- integration: valida integração entre API, banco e serviços.
A visão de implantação descreve a topologia de execução em produção.
Fonte: Equipe RetinaScan, 2026.
No processo da disciplina, a visão de dados substitui a visão de casos de uso para representar o domínio e a persistência da solução.
O domínio de dados da solução está detalhado em Modelagem do Banco de Dados, incluindo entidades como Usuario, Paciente, Atendimento, Exame, Imagem, Analise e Revisao.
Nesta arquitetura:
- PostgreSQL armazena dados estruturados e históricos.
- MinIO armazena artefatos binários (imagens e derivados).
- O vínculo entre registros do banco e arquivos no storage garante rastreio fim a fim.
| Decisão | Justificativa | Impacto |
|---|---|---|
| Entrada única via Nginx | Centraliza segurança, roteamento e TLS | Maior controle operacional |
| Node.js como core | Consolida regras de domínio e gestão de usuários | Menor acoplamento com inferência |
| FastAPI para inferência | Isola carga computacional do modelo | Escala independente de serviço |
| Redis + Celery | Permite processamento assíncrono resiliente | Melhor tempo de resposta da API |
| PostgreSQL + MinIO | Separação entre dado transacional e binário | Melhor desempenho e manutenção |
- Fila assíncrona congestionada em picos. Mitigação: escalar workers e aplicar monitoramento de fila.
- Ponto único de entrada no proxy. Mitigação: política de backup de configuração e observabilidade do Nginx.
- Divergência entre metadados e arquivos de imagem. Mitigação: validação transacional de vínculo entre banco e storage.
| Versão | Data | Descrição | Autor | Revisor |
|---|---|---|---|---|
1.0 |
12/04/2026 | Criação do documento de arquitetura | Yan Luca Viana | |
1.1 |
26/04/2026 | Reestruturação do documento para o formato 4+1 (lógica, processos, implementação, implantação e dados) | Zenilda Vieira e Github Copilot |