refactor: modulariza arquitetura do backend e frontend

- backend: separa lógica de machine learning em services, rotas em api e configs em core

- frontend: isola requisições HTTP em api_client e componentes visuais de formulário em forms

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.py[cod]
+*$py.class

app/api/__init__.py

@@ -0,0 +1 @@
+# Inicializa a camada de api

app/api/routes.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+from app.schemas import CustomerData
+from app.services.prediction import prediction_service
+
+router = APIRouter()
+
+@router.get("/")
+def home():
+    return {"status": "online", "module": "production_api"}
+
+@router.post("/predict")
+def predict_cluster(customer: CustomerData):
+    # Converte o Pydantic model para dict
+    data_dict = customer.model_dump()
+    
+    # Executa a predição via serviço
+    result = prediction_service.predict(data_dict)
+    
+    return result

app/core/__init__.py

@@ -0,0 +1 @@
+# Inicializa o módulo core

app/core/config.py

@@ -0,0 +1,13 @@
+import os
+
+class Settings:
+    # Obtendo o diretório raiz do projeto (subindo de app/core/config.py para a raiz)
+    BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    MODELS_DIR = os.path.join(BASE_DIR, "models")
+    
+    # Adicionando nomes dos arquivos de modelo para ficar centralizado
+    SCALER_PATH = os.path.join(MODELS_DIR, 'standard_scaler.joblib')
+    KMEANS_PATH = os.path.join(MODELS_DIR, 'kmeans_model.joblib')
+    RF_PATH = os.path.join(MODELS_DIR, 'random_forest_model.joblib')
+
+settings = Settings()

app/main.py

@@ -1,48 +1,7 @@
 from fastapi import FastAPI
-import joblib
-import pandas as pd
-import os
-from .schemas import CustomerData
-from .personas import PERSONAS
-
-# Caminho relativo para os modelos
-BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-MODELS_DIR = os.path.join(BASE_DIR, "models")
-
-scaler = joblib.load(os.path.join(MODELS_DIR, 'standard_scaler.joblib'))
-kmeans = joblib.load(os.path.join(MODELS_DIR, 'kmeans_model.joblib'))
-rf_model = joblib.load(os.path.join(MODELS_DIR, 'random_forest_model.joblib'))
+from app.api.routes import router
 
 app = FastAPI(title="Credit Card Clustering API")
 
-@app.get("/")
-def home():
-    return {"status": "online", "module": "production_api"}
-
-@app.post("/predict")
-def predict_cluster(customer: CustomerData):
-    data_dict = customer.model_dump()
-    df_input = pd.DataFrame([data_dict])
-    
-    # Reordenar as colunas para o exato padrão que o Scikit-Learn espera no modelo treinado
-    expected_features = [
-        'BALANCE_FREQUENCY', 'PURCHASES', 'CASH_ADVANCE', 
-        'ONEOFF_PURCHASES_FREQUENCY', 'CREDIT_LIMIT', 'PRC_FULL_PAYMENT', 
-        'TENURE', 'CREDIT_UTILIZATION', 'PAYMENT_RATIO'
-    ]
-    df_input = df_input[expected_features]
-
-    scaled_data = scaler.transform(df_input)
-    
-    # O scaler retorna um array numpy (sem nome de colunas). 
-    # Para evitar o "UserWarning: X does not have valid feature names", transformamos de volta em DataFrame:
-    scaled_df = pd.DataFrame(scaled_data, columns=expected_features)
-
-    cluster = int(kmeans.predict(scaled_df)[0])
-    proba = rf_model.predict_proba(scaled_df)[0]
-
-    return {
-        "cluster_id": cluster,
-        "persona": PERSONAS.get(cluster),
-        "confidence": f"{max(proba)*100:.2f}%"
-    }
+# Inclui as rotas definidas em app/api/routes.py
+app.include_router(router)

app/services/__init__.py

@@ -0,0 +1 @@
+# Inicializa a camada de serviços

app/services/prediction.py

@@ -0,0 +1,42 @@
+import joblib
+import pandas as pd
+from app.core.config import settings
+from app.personas import PERSONAS
+
+class PredictionService:
+    def __init__(self):
+        # Carrega os modelos uma única vez quando o serviço é instanciado
+        self.scaler = joblib.load(settings.SCALER_PATH)
+        self.kmeans = joblib.load(settings.KMEANS_PATH)
+        self.rf_model = joblib.load(settings.RF_PATH)
+        
+        self.expected_features = [
+            'BALANCE_FREQUENCY', 'PURCHASES', 'CASH_ADVANCE', 
+            'ONEOFF_PURCHASES_FREQUENCY', 'CREDIT_LIMIT', 'PRC_FULL_PAYMENT', 
+            'TENURE', 'CREDIT_UTILIZATION', 'PAYMENT_RATIO'
+        ]
+
+    def predict(self, data_dict: dict) -> dict:
+        df_input = pd.DataFrame([data_dict])
+        
+        # Reordenar as colunas para o exato padrão que o Scikit-Learn espera no modelo treinado
+        df_input = df_input[self.expected_features]
+
+        # Normalizar
+        scaled_data = self.scaler.transform(df_input)
+        
+        # Transformamos de volta em DataFrame para evitar warnings do Scikit-Learn
+        scaled_df = pd.DataFrame(scaled_data, columns=self.expected_features)
+
+        # Predição com K-Means e Confiança com Random Forest
+        cluster = int(self.kmeans.predict(scaled_df)[0])
+        proba = self.rf_model.predict_proba(scaled_df)[0]
+
+        return {
+            "cluster_id": cluster,
+            "persona": PERSONAS.get(cluster),
+            "confidence": f"{max(proba)*100:.2f}%"
+        }
+
+# Instância Singleton para ser usada nos roteadores
+prediction_service = PredictionService()

ui/components/__init__.py

@@ -0,0 +1 @@
+# Inicializa a camada de componentes da UI

ui/components/forms.py

@@ -0,0 +1,32 @@
+import streamlit as st
+
+def render_input_form():
+    """Renderiza o formulário de entrada e retorna o payload caso preenchido, ou None."""
+    st.subheader("📊 Insira os Dados Financeiros do Cliente")
+    
+    col1, col2 = st.columns(2)
+    with col1:
+        bal_freq = st.slider("Frequência de Saldo (0 a 1)", 0.0, 1.0, 0.8, help="Proporção de meses em que o saldo da conta foi atualizado (1 = todos os meses).")
+        purchases = st.number_input("Total de Compras na Fatura ($)", 0.0, 50000.0, 1000.0, help="Valor total em dinheiro de todas as compras feitas pelo cliente.")
+        oneoff_freq = st.slider("Frequência de Compras à Vista (0 a 1)", 0.0, 1.0, 0.5, help="Frequência com que o cliente faz compras de parcela única (à vista).")
+        cash_adv = st.number_input("Saques em Espécie (Cash Advance - $)", 0.0, 50000.0, 0.0, help="Valor sacado em dinheiro vivo usando o limite do cartão.")
+        credit_limit = st.number_input("Limite de Crédito Total ($)", 0.0, 50000.0, 5000.0, help="O limite máximo de crédito disponível para o usuário.")
+    
+    with col2:
+        prc_full = st.slider("Taxa de Pagamentos Integrais (0 a 1)", 0.0, 1.0, 0.0, help="Frequência em que o cliente paga o valor total da fatura (sem entrar no rotativo).")
+        tenure = st.selectbox("Tempo de Conta (Meses)", [6, 7, 8, 9, 10, 11, 12], index=6, help="Há quanto tempo (em meses) o cliente possui este cartão de crédito.")
+        cred_util = st.slider("Nível de Utilização de Crédito", 0.0, 2.0, 0.3, help="Relação entre o saldo devedor e o limite do cartão. Exemplo: 0.5 significa que usou 50% do limite. Se for 1.77, o cliente estourou o limite em 77%!")
+        pay_ratio = st.number_input("Proporção de Pagamento", 0.0, 100.0, 1.0, help="Proporção entre o valor que o cliente paga e a dívida real dele. Valores maiores indicam que o cliente abate mais a dívida.")
+    
+    st.markdown("---")
+    
+    # Se o botão for clicado, montamos o payload e retornamos
+    if st.button("🧠 Executar Motor de Inteligência", use_container_width=True):
+        return {
+            "BALANCE_FREQUENCY": bal_freq, "PURCHASES": purchases,
+            "ONEOFF_PURCHASES_FREQUENCY": oneoff_freq, "CASH_ADVANCE": cash_adv,
+            "CREDIT_LIMIT": credit_limit, "PRC_FULL_PAYMENT": prc_full,
+            "TENURE": tenure, "CREDIT_UTILIZATION": cred_util, "PAYMENT_RATIO": pay_ratio
+        }
+    
+    return None

ui/services/__init__.py

@@ -0,0 +1 @@
+# Inicializa a camada de serviços da UI

ui/services/api_client.py

@@ -0,0 +1,18 @@
+import requests
+
+def predict_persona(payload: dict) -> dict:
+    """Envia os dados do cliente para a API e retorna o resultado."""
+    try:
+        # Porta 8080 onde o FastAPI está rodando dentro do container
+        response = requests.post("http://127.0.0.1:8080/predict", json=payload)
+        
+        if response.status_code == 200:
+            return {"success": True, "data": response.json()}
+        else:
+            return {"success": False, "error": "Erro ao processar dados na API."}
+            
+    except Exception as e:
+        return {
+            "success": False, 
+            "error": f"Erro de conexão com a API. Detalhes: {str(e)}"
+        }

ui/ui.py

@@ -1,48 +1,22 @@
 import streamlit as st
-import requests
+from components.forms import render_input_form
+from services.api_client import predict_persona
 
 st.set_page_config(page_title="Inteligência de Personas", layout="wide")
 
 st.title("💳 Inteligência de Personas de Clientes")
 st.markdown("Descubra o perfil comportamental do seu cliente de cartão de crédito utilizando Machine Learning avançado.")
 
-# Interface de entrada
-st.subheader("📊 Insira os Dados Financeiros do Cliente")
+# Renderiza o formulário e pega o payload caso o botão tenha sido clicado
+payload = render_input_form()
 
-col1, col2 = st.columns(2)
-with col1:
-    bal_freq = st.slider("Frequência de Saldo (0 a 1)", 0.0, 1.0, 0.8, help="Proporção de meses em que o saldo da conta foi atualizado (1 = todos os meses).")
-    purchases = st.number_input("Total de Compras na Fatura ($)", 0.0, 50000.0, 1000.0, help="Valor total em dinheiro de todas as compras feitas pelo cliente.")
-    oneoff_freq = st.slider("Frequência de Compras à Vista (0 a 1)", 0.0, 1.0, 0.5, help="Frequência com que o cliente faz compras de parcela única (à vista).")
-    cash_adv = st.number_input("Saques em Espécie (Cash Advance - $)", 0.0, 50000.0, 0.0, help="Valor sacado em dinheiro vivo usando o limite do cartão.")
-    credit_limit = st.number_input("Limite de Crédito Total ($)", 0.0, 50000.0, 5000.0, help="O limite máximo de crédito disponível para o usuário.")
-
-with col2:
-    prc_full = st.slider("Taxa de Pagamentos Integrais (0 a 1)", 0.0, 1.0, 0.0, help="Frequência em que o cliente paga o valor total da fatura (sem entrar no rotativo).")
-    tenure = st.selectbox("Tempo de Conta (Meses)", [6, 7, 8, 9, 10, 11, 12], index=6, help="Há quanto tempo (em meses) o cliente possui este cartão de crédito.")
-    cred_util = st.slider("Nível de Utilização de Crédito", 0.0, 2.0, 0.3, help="Relação entre o saldo devedor e o limite do cartão. Exemplo: 0.5 significa que usou 50% do limite. Se for 1.77, o cliente estourou o limite em 77%!")
-    pay_ratio = st.number_input("Proporção de Pagamento", 0.0, 100.0, 1.0, help="Proporção entre o valor que o cliente paga e a dívida real dele. Valores maiores indicam que o cliente abate mais a dívida.")
-
-st.markdown("---")
-
-if st.button("🧠 Executar Motor de Inteligência", use_container_width=True):
-    payload = {
-        "BALANCE_FREQUENCY": bal_freq, "PURCHASES": purchases,
-        "ONEOFF_PURCHASES_FREQUENCY": oneoff_freq, "CASH_ADVANCE": cash_adv,
-        "CREDIT_LIMIT": credit_limit, "PRC_FULL_PAYMENT": prc_full,
-        "TENURE": tenure, "CREDIT_UTILIZATION": cred_util, "PAYMENT_RATIO": pay_ratio
-    }
+if payload:
+    # Faz a requisição à API usando o cliente isolado
+    response = predict_persona(payload)
     
-    try:
-        # Porta 8080 onde o FastAPI está rodando dentro do container
-        response = requests.post("http://127.0.0.1:8080/predict", json=payload)
-        
-        if response.status_code == 200:
-            res = response.json()
-            st.success(f"### 🎯 Resultado da Classificação: **{res['persona']}**")
-            st.metric("Confiança do Modelo (Random Forest)", res['confidence'])
-        else:
-            st.error("Erro ao processar dados na API.")
-            
-    except Exception as e:
-        st.error("Erro de conexão com a API. Verifique se o backend (FastAPI) está rodando na porta 8080.")
+    if response["success"]:
+        res = response["data"]
+        st.success(f"### 🎯 Resultado da Classificação: **{res['persona']}**")
+        st.metric("Confiança do Modelo (Random Forest)", res['confidence'])
+    else:
+        st.error(response["error"])