Skip to main content

Planejamento Backend

Introdução

  A arquitetura de backend do Peerseed é baseada em um conjunto de microsserviços independentes, escritos em Python. A escolha por esta abordagem visa garantir alta escalabilidade, resiliência e manutenibilidade, permitindo que equipes possam desenvolver, implantar e escalar cada domínio de negócio de forma autônoma.

  Este documento estabelece a stack tecnológica padrão, a estrutura de diretórios e os padrões de comunicação que devem ser seguidos por todos os serviços de backend, a fim de manter a coesão e a qualidade técnica em todo o ecossistema.

Stack Tecnológica Principal

 Para garantir consistência e produtividade, todos os serviços de backend do Peerseed devem ser construídos utilizando a seguinte stack de tecnologias:

ComponenteTecnologia/Padrão RecomendadoPrincipal Vantagem
Framework APIFastAPIPerformance, async nativo, docs e validação automáticas
ORM (DB)SQLAlchemy 2.0+Padrão de mercado, produtivo e com suporte async
Migrações de SchemaAlembicVersionamento seguro do banco de dados
Validação/SerializaçãoPydanticIntegrado ao FastAPI, garante a integridade dos dados
AutenticaçãoJWT com OAuth2Padrão stateless e seguro para microsserviços
DependênciasPoetryGerenciamento moderno e builds repetíveis
TestesPytestPadrão da comunidade Python, flexível e poderoso

Detalhamento dos Componentes da Stack

Framework de API: FastAPI

  O FastAPI é a fundação de todos os nossos serviços. Sua alta performance e suporte nativo a operações assíncronas (async/await) são essenciais para construir uma plataforma responsiva e escalável, capaz de lidar com um grande volume de operações de I/O (consultas a banco de dados, chamadas a APIs externas), em conformidade com nossos requisitos de performance (RNF-ED-01).

Interação com Banco de Dados: SQLAlchemy

  A comunicação com o banco de dados PostgreSQL é abstraída pelo SQLAlchemy, o ORM padrão da comunidade Python. Utilizamos exclusivamente seu motor assíncrono (create_async_engine), que se integra ao FastAPI. As tabelas do banco de dados são mapeadas para classes Python (models), o que aumenta a produtividade e a segurança do código.

alidação de Dados: Pydantic

  O Pydantic é utilizado para definir schemas de dados claros para todas as operações de API. Adotamos o padrão de ter schemas específicos para entrada (Request Models) e saída (Response Models), o que nos proporciona:

Validação Automática: Requisições com dados inválidos ou faltando são rejeitadas automaticamente pelo framework.

Segurança: Evita o vazamento acidental de dados internos, expondo apenas os campos definidos no schema de resposta.

Documentação Automática: Os schemas Pydantic são a fonte da verdade para a geração da documentação OpenAPI.

Migrações de Banco de Dados: Alembic

  Toda alteração no schema do banco de dados (modelos do SQLAlchemy) deve ser acompanhada por um script de migração gerado pelo Alembic. Isso garante que a evolução do banco de dados seja controlada, versionada e possa ser aplicada de forma segura e consistente em qualquer ambiente.

Autenticação e Autorização: JWT (OAuth2)

  A segurança entre os serviços é baseada em JSON Web Tokens. O Serviço de Contas atua como o provedor de identidade, emitindo um JWT para o usuário após um login bem-sucedido. Todas as chamadas subsequentes para qualquer microsserviço devem conter este token no cabeçalho Authorization. Cada serviço é responsável por validar a assinatura e as permissões do token antes de processar a requisição.

Gerenciamento de Dependências: Poetry

  Poetry é a ferramenta padrão para gerenciamento de dependências e ambientes virtuais em todos os projetos. O uso do pyproject.tomle do poetry.lock garante que todos os ambientes (desenvolvimento, teste, produção) sejam idênticos, eliminando problemas de consistência.

Testes: Pytest

 A qualidade do software é garantida através de uma suíte de testes automatizados escritos com Pytest. O FastAPI fornece um TestClient que facilita a escrita de testes de integração, permitindo simular requisições à API sem a necessidade de um servidor em execução.

Estrutura de Diretórios Padrão

Para assegurar a consistência e facilitar a navegação entre os projetos, todos os microsserviços devem seguir a estrutura de diretórios abaixo:

/nome-do-servico
├── /alembic/ # Scripts de migração do banco de dados (Alembic)
├── /app/
│ ├── /api/ # Endpoints/Routers da API, camada de entrada de requisições.
│ ├── /core/ # Configurações centrais da aplicação (ex: settings).
│ ├── /crud/ # Funções de acesso aos dados (lógica de banco de dados).
│ ├── /models/ # Classes que representam as tabelas do banco (SQLAlchemy).
│ ├── /schemas/ # Classes de validação de dados da API (Pydantic).
│ └── main.py # Ponto de entrada da aplicação FastAPI.
├── /tests/ # Testes automatizados (Pytest).
├── pyproject.toml # Definição do projeto e dependências (Poetry).
└── poetry.lock # Arquivo de lock das dependências.

Padrões de Comunicação entre Serviços

 A comunicação no ecossistema de microsserviços do Peerseed segue dois padrões principais:

Comunicação Síncrona (RESTful APIs)

Quando usar: Para interações de comando ou consulta que exigem uma resposta imediata.

Exemplo: O Frontend solicita ao Serviço de Marketplace a lista de CPRs disponíveis. A requisição precisa ser respondida na hora com os dados.

Mecanismo: Chamadas HTTP/S diretas entre os serviços, geralmente orquestradas através de um API Gateway, que atua como o ponto de entrada único para todas as requisições externas.

Comunicação Assíncrona (Orientada a Eventos)

Quando usar: Para desacoplar os serviços e para processos que podem ser executados em background, sem que o solicitante precise esperar por uma resposta.

Exemplo: Quando o Serviço de Carteira confirma o pagamento de uma parcela, ele publica um evento PagamentoConfirmado. O Serviço de Notificações e o Serviço de Distribuição escutam este evento e reagem a ele de forma independente, sem que o Serviço de Carteira precise saber de sua existência.

Mecanismo: Utilização de um Message Broker (como RabbitMQ ou AWS SQS), que já foi previsto em nossos diagramas de sequência.