Pular para o conteúdo principal

ADR-001: Stack Tecnológica e Linguagens

Título

Definição da stack tecnológica e linguagens de programação para o projeto Cruzeiro e Remo em Números (Next.js, NestJS, Prisma e Python).

Status

Aceito

Data

2026-02-12

Contexto​

O projeto requer uma plataforma web escalável que atenda a dois clientes simultâneos (Clube do Remo e Cruzeiro Esporte Clube) consumindo a mesma base de dados através de uma API Multi-tenant. Além das requisições síncronas de listagem e filtragem, o ecossistema exige a raspagem, tratamento e inserção de dados históricos provenientes de planilhas locais e APIs de terceiros (ETL). A escolha da stack técnica precisa garantir consistência de tipagem, agilidade de desenvolvimento (DX) e segurança.

Decisão​

A equipe decidiu utilizar a seguinte composição tecnológica:

  • Frontend: React com o framework Next.js.
  • Backend: NestJS (Node.js).
  • Camada de Dados (ORM): Prisma.
  • Extração, Transformação e Carga (ETL): Python.

Essa stack garante consistência em todo o ecossistema Web, utilizando TypeScript de ponta a ponta no Frontend e no Backend, ao mesmo tempo em que delega o processamento pesado de limpeza dos dados históricos (sanitização de datas, autores de gols e valores monetários) para o ecossistema Python. O Prisma complementa o NestJS traduzindo o banco de dados diretamente para tipos estáticos em TypeScript, blindando a API de erros estruturais.

As alternativas avaliadas foram:

CamadaOpção DescartadaMotivo
FrontendReact puroExige configuração manual de roteamento e otimização
BackendExpressMinimalista; exige criação de arquitetura do zero
ORMTypeORMUso de decorators polui o código das entidades
ETLNode.jsPython é o padrão da indústria para manipulação de dados (pandas) e scraping (BeautifulSoup)

Consequências​

Positivas:

  • Consistência: Adoção de TypeScript no cliente e no servidor previne falhas de comunicação entre Frontend e API.
  • Produtividade (DX): O Prisma elimina grande parte do atrito de lidar com SQL manual; o roteamento do Next.js acelera a criação de novas telas.
  • Eficiência no tratamento de dados: O Python reduzirá drasticamente o tempo necessário para formatar milhares de linhas das planilhas históricas.
  • Escalabilidade: A arquitetura modular do NestJS e a vasta comunidade do React facilitam o crescimento futuro do projeto.

Negativas:

  • Curva de aprendizado: Desenvolvedores precisarão se adaptar às convenções rigorosas do NestJS e à gestão de estado no Next.js.
  • Ecossistema duplo: A inserção do Python exige a manutenção de dois ambientes de desenvolvimento distintos (Node/npm e Python/venv).

Conformidade​

  • Todo código de Frontend e Backend deve ser escrito em TypeScript.
  • Scripts ETL devem ser escritos em Python, isolados em seu próprio ambiente virtual (venv).
  • O schema do banco de dados deve ser gerenciado exclusivamente via schema.prisma.

Observações​

  • Autores: Antonio G. Castro, João Pedro Santos de Brito
  • Versão: 1.1
  • Changelog:
    • 1.0 - 12/02/2026: versão inicial proposta (Antonio G. Castro)
    • 1.1 - 19/02/2026: ajuste de especificações técnicas da stack (João Pedro S. de Brito)

Referências: