No setor de Telecomunicações, a maioria das ações de retenção ocorre tarde demais: apenas quando o cliente entra em contato para cancelar. Essa abordagem reativa gera custos operacionais elevados e baixa taxa de reversão. O verdadeiro problema não é a saída do cliente, mas a incapacidade de identificar sinais silenciosos de insatisfação antes que a decisão de cancelamento seja tomada.
O Reter+ é um motor de inteligência preditiva projetado para transformar a retenção de reativa para proativa.
Utilizando algoritmos de Machine Learning treinados em dados comportamentais e financeiros, o sistema atua como um "radar de risco", classificando a base de clientes em tempo real.
Como funciona a entrega de valor:
- Scoring de Risco: Cada cliente recebe uma probabilidade de evasão (0-100%), permitindo que as equipes de marketing foquem recursos apenas nos casos críticos.
- Classificação Binária: O sistema aplica um limiar de decisão (threshold) otimizado para maximizar a captura de churners reais (Recall), categorizando o cliente explicitamente como "Em Risco" ou "Seguro".
Adotamos uma arquitetura de Microserviços para separar responsabilidades e garantir escalabilidade:
- Frontend (Interface Web): Desenvolvido com HTML5 e CSS com framework Bootstrap. Responsável por enviar os dados via JSON para o endpoint de predição e exibe o resultado em tempo real.
- Backend (Gateway & Orchestrator): Desenvolvido em Java/Spring Boot. Responsável por receber requisições, validar dados (Bean Validation), segurança e orquestrar a chamada ao modelo.
- Model API (Inference Engine): Desenvolvido em Python/FastAPI. Responsável por carregar o modelo treinado (
.joblib) e realizar a inferência matemática.
graph LR
User[Cliente/Frontend] -- POST /prever --> Java[Spring Boot Backend]
Java -- Validação OK --> Py[FastAPI Model Service]
Py -- Carrega Modelo --> Model[(Churn Model)]
Py -- Retorna Probabilidade --> Java
Java -- Resposta JSON --> User
Para detalhes específicos de integração, consulte:
- Referência da API e Contratos: Endpoints, tipos de dados e campos obrigatórios.
- Guia de Erros e Status Codes: Padrões de resposta para validações e falhas de integração.
- Performance do Modelo: Métricas de Acurácia, Precision e Recall.
A forma mais simples de rodar a solução completa (Frontend + Backend + ML) é utilizando o Docker Compose.
- Docker & Docker Compose instalados e rodando.
- Clone o repositório:
git clone https://github.com/windsonPatricio/Hackathon-TelcoCustomerChurn.git
- Navegue até o diretório raiz do projeto:
cd Hackathon-TelcoCustomerChurn
- Execute o Docker Compose:
docker-compose up --build
Nota: Este comando irá construir a imagem do serviço Python (ML) e compilar/subir a aplicação Java (Backend).
- Acesse as APIs:
Após a inicialização, os serviços estarão disponíveis nas seguintes portas:
- Frontend (Principal):
http://localhost - Backend Java:
http://localhost:8080 - Model API (Interna):
http://localhost:8000
- HTML5
- CSS
- JavaScript
- Axios
- Nginx
- Java 21
- Spring Boot 4.0.0
- Spring Boot Starter Web: (MVC e Tomcat)
- Spring Boot Starter Validation: (Bean Validation / Hibernate Validator)
- Spring Boot DevTools: (Hot reload)
- Spring Swagger: (Documentação de API)
- Maven
- Python 3.11
- Scikit-Learn (pipelines, modelagem)
- Pandas & Numpy
- FastAPI (Serviço de Inferência)
- uv (Gerenciador de pacotes Python moderno)
Trabalho desenvolvido em conjunto pelos times de Backend e Data Science.
| Colaborador | Função | GitHub |
|---|---|---|
| Augusto Brandão | Backend Developer | @gutoobrandao |
| Windson Patricio | Backend Developer | @windsonPatricio |
| Brizza Nathielly | Backend Developer | @whoisbrizza |
| Lucas Zimmermann | Backend Developer | @zzzimmer |
| Marcelle Carolina | Data Scientist | @Marcellecarol |
| Joel Victor | Data Scientist | @jvsobrinho |