🌍 Unified Leads Dashboard (End-to-End Pipeline)

Simulação completa de um ciclo de vida de dados: da geração e ingestão à visualização.

Este projeto demonstra a construção de um pipeline de dados (ETL) integrado a um banco de dados em nuvem (Neon Tech) e um frontend interativo para análise de KPIs. O foco principal é a integração segura de componentes e a visualização de métricas em tempo real.

---

🏗️ Arquitetura e Fluxo de Dados

O sistema opera em três estágios distintos, garantindo a separação de responsabilidades entre a geração, o processamento e a apresentação dos dados.

graph TD;
    A[🏭 leads.py] -->|Gera Mock Data| B(Arquivo Local);
    B --> C{⚙️ etl_carga.py};
    C -->|Extract & Transform| D[Tratamento de Dados];
    D -->|Load| E[(☁️ Neon PostgreSQL)];
    E <-->|Query SQL| F[📊 app_unificado.py];
    F -->|Renderiza| G[Frontend Streamlit];

Loading

Detalhes dos Componentes:

1. Geração de Dados (leads.py): Script python que cria massa de dados fictícia, simulando diversas fontes de tráfego e geolocalizações.
2. Pipeline ETL (etl_carga.py):
   • Extract: Captura os dados brutos.
   • Transform: Normaliza strings, trata valores nulos e valida tipos de dados.
   • Load: Conecta-se de forma segura ao PostgreSQL e insere os dados na tabela consolidada all_leads.
3. Visualização (app_unificado.py): Interface desenvolvida em Streamlit que consome os dados diretamente do banco, garantindo que as métricas de "Total Leads" e "Top Locations" estejam sempre atualizadas.

---

🚀 Funcionalidades

• ✅ Conexão Segura: Utilização de variáveis de ambiente para proteger credenciais do banco.
• ✅ ETL Automatizado: Script único para limpeza e carga de dados.
• ✅ Dashboard Interativo: Filtros e gráficos dinâmicos usando Plotly.
• ✅ Cloud Database: Integração real com PostgreSQL hospedado na Neon Tech.

🛠️ Tech Stack

• Linguagem: Python
• Banco de Dados: PostgreSQL (Neon Tech)
• Bibliotecas Principais:
  • pandas (Manipulação de dados)
  • psycopg2 (Driver PostgreSQL)
  • streamlit (Frontend)
  • plotly (Visualização)
  • python-dotenv (Segurança/Env vars)

---

⚙️ Como Executar o Projeto

Siga os passos abaixo para configurar o ambiente localmente.

1. Clonar o repositório

git clone [https://github.com/SEU-USUARIO/NOME-DO-REPO.git](https://github.com/SEU-USUARIO/NOME-DO-REPO.git)
cd NOME-DO-REPO

2. Configurar o Ambiente Virtual

# Criação do venv
python -m venv venv

# Ativação (Windows)
.\venv\Scripts\activate

# Ativação (Linux/Mac)
source venv/bin/activate

3. Instalar Dependências

pip install -r requirements.txt

4. Configuração de Segurança (.env)

⚠️ Importante: Este projeto não versiona senhas. Você deve criar um arquivo .env na raiz do projeto seguindo o modelo abaixo:

Arquivo .env:

DATABASE_URL=postgresql://seu_usuario:sua_senha@endpoint-do-neon.tech/neondb

(Consulte o arquivo .env.example para referência)

5. Executar o Pipeline

Se for a primeira execução, popule o banco de dados:

# 1. Gerar dados falsos
python leads.py

# 2. Executar o ETL (Carga no Banco)
python etl_carga.py

6. Iniciar o Dashboard

streamlit run app_unificado.py

---

🛡️ Segurança e Boas Práticas

Este projeto foi desenvolvido com foco em segurança de aplicação:

• Segregação de Credenciais: Nenhuma senha é "hardcoded" no código fonte.
• Tratamento de Erros: O dashboard possui tratativas try/except para falhas de conexão, evitando exposição de stack traces sensíveis ao usuário final.
• Validação de Dados: Verificação de integridade antes da inserção no banco SQL.

---

Desenvolvido para fins de estudo em Data Engineering e AppSec.

🛡️ Preview da Aplicação:

Dashboard com os leads gerados vindos de diversas fontes.