InsightSent — Inteligência de Dados e Análise de Sentimentos

 

Índice

• Descrição do Projeto
• Arquitetura da Solução
• Metodologia de Data Science
• Documentação da API (Endpoints)
• Exemplos de Requisição e Resposta (JSON)
• Estrutura do Projeto & Visão Geral do Repositório
• Execução do Projeto
• Fluxogramas do Sistema
• Equipe

 

📝 Descrição do Projeto

O InsightSent é uma plataforma de inteligência de dados desenvolvida para transformar o caos de feedbacks não estruturados em decisões estratégicas.

Em um cenário onde 80% dos feedbacks de clientes são ignorados por incapacidade de processamento manual, o InsightSent atua como uma central de inteligência que processa textos em tempo real, identifica o idioma (Português/Espanhol) e classifica o sentimento com alta precisão.

Diferenciais

• 🚀 Performance: Respostas em menos de 100ms.
• 🌍 Multilíngue: Detecção automática de PT-BR e ES (Espanhol).
• 📊 Inteligência Visual: Dashboard integrado para acompanhamento de métricas.
• 🔒 Segurança: Arquitetura protegida com autenticação via Token JWT.

⚙️ Arquitetura da Solução

O projeto adota uma arquitetura de Microserviços Conteinerizados, garantindo escalabilidade e isolamento de responsabilidades.

1. Backend (O Maestro)

• Tecnologia: Java 21 + Spring Boot 3.4.5.
• Função: Orquestração de chamadas, gestão de segurança (Spring Security), validação de dados e comunicação com o banco.
• Comunicação: Utiliza OpenFeign para comunicação HTTP de baixa latência com o serviço de IA.

2. Data Science (O Cérebro)

• Tecnologia: Python 3.11 + FastAPI + Uvicorn.
• Modelo: Pipeline de Machine Learning utilizando TF-IDF Vectorizer (para transformar texto em números) e Regressão Logística (para classificação).
• Treinamento: Modelo treinado com um dataset unificado de ~470.000 avaliações (Olist, B2W e Amazon Reviews).

3. Frontend (A Interface)

• Tecnologia: Vanilla JavaScript (ES6+), HTML5 e CSS3.
• Design: Interface limpa, responsiva e focada na experiência do usuário (UX), comunicando-se via Fetch API com o Backend.

4. Infraestrutura de Dados

• Banco de Dados: PostgreSQL 15 rodando em container Docker.
• Persistência: Armazena usuários, logs de auditoria e histórico completo das análises para geração de insights futuros.

 

Todas as Tecnologias Utilizadas:

Backend (Java/Spring)	Data Science (Python)	Infra/DevOps
Java 17 + Spring Boot 3 Spring Web (REST) - Endpoints Spring Security (JWT) Spring Validation Lombok OpenFeign (HTTP client → Python) H2 Database (em memória) JUnit + Mockito (testes) Swagger/OpenAPI (Docs)	Python 3.10 Pandas, NumPy, Scikit-learn Joblib (persistência) FastAPI + Uvicorn Datasets (Hugging Face/Kaggle) Imbalanced-learn NLTK / SpaCy (NLP) Matplotlib / Seaborn	Git / GitHub (Monorepo) Docker + Docker Compose GitHub Actions (CI/CD) PlantUML (fluxogramas)

Note

O código do front-end encontra-se em funcionamento e integrado ao backend. Documentação e melhorias visuais poderão ser adicionadas nas próximas iterações do projeto.

 

🧠 Metodologia de Data Science

O "cérebro" da aplicação utiliza um pipeline robusto para garantir precisão em múltiplos idiomas.

1. Datasets Unificados: Treinamento realizado com ~470.000 avaliações combinadas de Olist (PT-BR), B2W (PT-BR) e Amazon Reviews (ES).
2. Balanceamento: Aplicação de SMOTE (Synthetic Minority Over-sampling Technique) para evitar viés em classes minoritárias.
3. Vetorização: Uso de TF-IDF para ponderar a relevância das palavras, ignorando ruídos (stopwords).
4. Modelo: Regressão Logística, escolhida pelo equilíbrio ideal entre precisão e velocidade de inferência (<100ms).

 

🔌 Documentação da API (Endpoints)

A API segue os padrões RESTful e está documentada via Swagger/OpenAPI. Abaixo estão as rotas principais para integração.

Autenticação & Usuários

Método	Endpoint	Descrição	Nível de Acesso
POST	/auth/register	Cadastra um novo usuário no sistema.	Público
POST	/auth/login	Autentica credenciais e retorna o Bearer Token.	Público

Core Business (Análise)

Método	Endpoint	Descrição	Nível de Acesso
POST	/analise	Envia um texto para processamento. Retorna o Sentimento, Nível de Confiança (%) e Idioma detectado.	Autenticado
GET	/analise/historico	Retorna todo o histórico de análises realizadas pelo usuário logado.	Autenticado

 

🔌 Exemplos de Requisição e Resposta (JSON)

Para facilitar a integração, abaixo estão os exemplos reais de uso da API documentados no Swagger.

1. Realizar Análise (POST /analise)

Envia um texto cru e recebe a classificação enriquecida com metadados. Requisição:

{
  "texto": "O prazo de entrega foi cumprido com excelência, adorei!"
}

Resposta (200 OK):

{
  "sentimento": "Positivo",
  "probabilidade": 0.9854,
  "idioma": "PT",
  "data_analise": "2026-01-18T14:30:00Z"
}

Note

O campo idioma é gerado dinamicamente pela biblioteca langdetect no serviço Python.

 

2. Histórico (GET /analise/historico)

Recupera os dados persistidos no PostgreSQL para popular o Dashboard. Resposta (200 OK):

[
  {
    "id": 153,
    "texto": "Não gostei do atendimento.",
    "sentimento": "Negativo",
    "probabilidade": 0.85,
    "idioma": "PT",
    "criado_em": "2026-01-18T10:00:00Z"
  },
  {
    "id": 154,
    "texto": "Me encanta este producto.",
    "sentimento": "Positivo",
    "probabilidade": 0.99,
    "idioma": "ES",
    "criado_em": "2026-01-18T10:05:00Z"
  }
]

 

📁 Estrutura do Projeto & Visão Geral do Repositório

hackathon-sentimentapi-analytics
│
├── backend/                # API Gateway e Regras de Negócio (Java/Spring)
│   ├── src/...             # Controllers, Services, SecurityConfig, DTOs
│   ├── pom.xml
│   └── Dockerfile          # Multi-stage build (Maven + OpenJDK 21)
│
├── data/                   # Microsserviço de ML (Python/FastAPI)
│   ├── notebooks/          # Jupyter Notebooks
│   ├── model/              # Modelo treinado (.joblib)
│   ├── app.py              # API de Predição e Langdetect
│   ├── requirements.txt    # Dependências Python
│   └── Dockerfile          # Python 3.11 Slim (Otimizado)
│
├── frontend/               # Interface Web (HTML/JS/CSS)
│   ├── index.html
│   ├── server.py
│   └── src/
│       ├── assets/
│       │   ├── css/        # Estilos
│       │   └── js/         # Lógica de consumo da API (Fetch)
│       └── pages/          # Telas (Login, Dashboard, Análise)
│
├── docs/                   # Documentação
│   └── fluxogramas/
│       ├── fluxoCadastro.png
│       ├── fluxoLogin.png
│       └── fluxoAnalise.png
│
├── docker-compose.yml      # Orquestração dos serviços e rede interna
└── README.md               # Documentação principal do projeto

 

🛠️ Execução do Projeto

Como Executar no (VSCODE)

Important

O serviço Python deve estar em execução antes de iniciar o backend Java. O backend Java depende do serviço Python estar em execução. Este projeto é composto por dois serviços principais que devem ser executados separadamente:

• Serviço de Machine Learning (Python + FastAPI)
• API Backend (Java + Spring Boot)

Pré-requisitos

Certifique-se de ter instalado:

1. Executando o Serviço de Machine Learning (Python):

Responsável por classificar o sentimento dos feedbacks.

Abra um terminal na raiz do projeto e rode o comando abaixo para acessar a pasta, instalar as dependências e rodar a aplicação:

cd data && pip install -r requirements.txt && uvicorn app:app --reload

Serviço	Documentação
http://localhost:8000	http://localhost:8000/docs

2. Executando o Backend (Java + Spring Boot)

Responsável por expor a API REST e integrar com o serviço Python.

Abra outro terminal na raiz do projeto e rode o comando abaixo para acessar a pasta e rodar a aplicação:

cd backend && mvn spring-boot:run

Serviço	Documentação
http://localhost:8080	http://localhost:8080/swagger-ui.html

3. Encerrando a Aplicação.

Fazer em ambos os terminais (Python e Java).

CTRL + C

 

Fluxo de Funcionamento

1. O cliente envia um feedback para a API Java

2. O backend chama o serviço Python via HTTP (OpenFeign)

3. O modelo de Machine Learning classifica o sentimento

4. O resultado é retornado e persistido no banco H2

 

Como Executar no (Docker)

O projeto foi desenhado para ser executado com um único comando, abstraindo a complexidade de configuração de ambientes.

Certifique-se de ter instalado:

Execute a aplicação:

Abra um terminal e rode o comando abaixo para baixar o repositório, entrar no diretório e subir os containers (Build & Run):

git clone https://github.com/amaro-netto/hackathon-sentimentapi-analytics.git && cd hackathon-sentimentapi-analytics && docker-compose up --build -d

Isso irá compilar o Java, construir a imagem Python, subir o banco PostgreSQL e configurar a rede interna.

Frontend	API Java (Swagger)	API Python (Docs)
http://localhost:80	http://localhost:8080/swagger-ui.html	http://localhost:8000/docs

 

📊 Fluxogramas do Sistema

Abaixo estão os fluxos principais da aplicação:

Pipeline

sequenceDiagram
    participant User as 👤 Usuário
    participant Front as 💻 Frontend
    participant Java as ☕ Backend API (Java)
    participant AI as 🧠 IA Service (Python)
    participant DB as 🗄️ PostgreSQL

    User->>Front: Digita o texto e clica em "Analisar"
    Front->>Java: POST /analise (c/ Token JWT)
    Java->>Java: Valida Token & Permissões
    Java->>AI: Envia texto cru (OpenFeign)
    AI->>AI: Detecta Idioma (PT/ES)
    AI->>AI: Vetorização (TF-IDF) + Predição
    AI-->>Java: Retorna JSON {sentimento, score, idioma}
    Java->>DB: Salva log da análise (Persistência)
    Java-->>Front: Retorna Resultado Completo
    Front-->>User: Exibe Gráfico de Confiança e Cor

Loading

🔐 Fluxo de Cadastro	🔑 Fluxo de Login	💬 Fluxo de Análise de Sentimento
Representa o processo de criação de um novo usuário no sistema.	Representa o processo de autenticação de um usuário no sistema.	Representa o processo de classificação automática de feedbacks em positivo, negativo ou neutro.

 

👥 Equipe DevstechOne

Este projeto foi desenvolvido com orgulho durante o Hackathon ONE II - Brasil. 📅 08 Dez 2025 - 21 Jan 2026

 

---

© 2026 InsightSent - Desenvolvido por DevstechOne.