Plataforma integrada de CRM para a V-Commerce, construída sobre a arquitetura Medalhão (Bronze → Silver → Gold) no Databricks. Centraliza dados de clientes, pedidos, produtos e suporte em dashboards analíticos com um agente de IA conversacional (Text-to-SQL).
v-commerce-crm-360/
├── data-engineering/ # Notebooks PySpark (Databricks)
│ ├── 01_bronze_vcommerce.ipynb
│ ├── 02_silver_vcommerce.ipynb
│ ├── 03_gold_vcommerce.ipynb
│ ├── silver-data-csvs/ # gerado pelo pipeline, não versionado
│ └── gold-data-csvs/ # gerado pelo pipeline, não versionado
│
├── backend/ # FastAPI (Python)
│ ├── alembic/ # Migrations do banco de dados
│ ├── app/
│ │ ├── core/
│ │ │ ├── dependencies.py # Injeções compartilhadas (auth, db, etc.)
│ │ │ └── security.py # Hash de senha e geração/validação de JWT
│ │ ├── models/ # Models SQLAlchemy
│ │ │ ├── bookmarkModel.py
│ │ │ ├── contactModel.py
│ │ │ ├── conversationModel.py
│ │ │ ├── goalModel.py
│ │ │ ├── productModel.py
│ │ │ ├── reviewModel.py
│ │ │ ├── saleModel.py
│ │ │ ├── sessionModel.py
│ │ │ ├── ticketModel.py
│ │ │ └── userModel.py
│ │ ├── routes/ # Routers FastAPI
│ │ │ ├── agentRouter.py
│ │ │ ├── authRouter.py
│ │ │ ├── bookmarkRouter.py
│ │ │ ├── contactDetailRouter.py
│ │ │ ├── contactRouter.py
│ │ │ ├── conversationRouter.py
│ │ │ ├── dashboardRouter.py
│ │ │ ├── goalRouter.py
│ │ │ ├── mentionRouter.py
│ │ │ ├── productRouter.py
│ │ │ ├── reviewRouter.py
│ │ │ ├── saleRouter.py
│ │ │ ├── ticketRouter.py
│ │ │ └── userRouter.py
│ │ ├── schemas/ # Schemas Pydantic
│ │ │ ├── agentSchemas.py
│ │ │ ├── authSchemas.py
│ │ │ ├── bookmarkSchemas.py
│ │ │ ├── contactDetailSchemas.py
│ │ │ ├── contactSchemas.py
│ │ │ ├── conversationSchemas.py
│ │ │ ├── dashboardSchemas.py
│ │ │ ├── goalSchemas.py
│ │ │ ├── productSchemas.py
│ │ │ ├── reviewSchemas.py
│ │ │ ├── salesSchemas.py
│ │ │ ├── ticketSchemas.py
│ │ │ └── userSchemas.py
│ │ ├── services/ # Lógica de negócio
│ │ │ ├── authService.py
│ │ │ ├── bookmarkService.py
│ │ │ ├── contactDetailService.py
│ │ │ ├── contactService.py
│ │ │ ├── conversationService.py
│ │ │ ├── dashboardService.py
│ │ │ ├── goalService.py
│ │ │ ├── productService.py
│ │ │ ├── reviewService.py
│ │ │ ├── saleService.py
│ │ │ ├── ticketService.py
│ │ │ └── userService.py
│ │ ├── config.py
│ │ └── main.py
│ ├── database/
│ │ ├── database.py
│ │ └── seed.py # Script de população do banco
│ ├── tests/ # Testes pytest
│ ├── .env.example
│ ├── Dockerfile
│ ├── alembic.ini
│ ├── pytest.ini
│ └── requirements.txt
│
├── frontend/ # React + TypeScript (Vite)
│ ├── public/
│ ├── src/
│ │ ├── Pages/ # Páginas da aplicação
│ │ │ ├── Chat/
│ │ │ ├── Contacts/
│ │ │ ├── Dashboard/
│ │ │ ├── Home/
│ │ │ ├── Login/
│ │ │ ├── Products/
│ │ │ ├── Sales/
│ │ │ ├── Tickets/
│ │ │ └── Unauthorized/
│ │ ├── components/
│ │ │ ├── atoms/ # Componentes base (Button, Input, Label...)
│ │ │ ├── molecules/ # Composições (ContactsTable, ProductsTable...)
│ │ │ └── organisms/ # Estruturas completas (AppFrame, ProtectedRoute...)
│ │ ├── contexts/
│ │ │ └── auth/
│ │ │ ├── AuthContext.tsx # Provider que mantém o usuário em estado
│ │ │ ├── context.ts # createContext + tipos
│ │ │ └── useAuth.tsx # Hook de consumo do contexto
│ │ ├── hooks/
│ │ ├── lib/
│ │ │ ├── api/ # Clientes HTTP por entidade
│ │ │ └── mocks/
│ │ └── types/
│ ├── Dockerfile
│ └── package.json
│
├── ai-agent/ # Agente de IA Text-to-SQL
│ ├── agent.py # Definição do agente e ferramentas
│ ├── database_tools.py # Conexão e execução de queries
│ ├── prompts.py # System prompt e instruções
│ └── test_agent.py # Script de testes interativo
│
├── docs/ # Documentação técnica por módulo
│ ├── data-engineering_doc/
│ │ └── README.md
│ ├── backend_doc/
│ │ └── README.md
│ ├── frontend_doc/
│ │ └── README.md
│ ├── ai-agent_doc/
│ │ └── README.md
│ └── decisions-doc.md
│
├── docker-compose.yml
└── README.md
- Documentação Frontend
- Documentação Backend
- Documentação Data Engineering
- Documentação Agente de IA
- Decisões Arquiteturais
Após rodar o pipeline, baixe os CSVs gerados e coloque-os nas pastas corretas:
Silver — tabelas brutas limpas, usadas pelo backend para consultas detalhadas:
data-engineering/silver-data-csvs/
Gold — tabelas agregadas, consumidas diretamente pelos endpoints e pelo agente de IA:
data-engineering/gold-data-csvs/
Essas pastas estão no
.gitignoree não são versionadas. É preciso baixá-las localmente e adicionar a pasta correta!
Com os CSVs nas pastas corretas, rode o script de seed (as dependências já estão no requirements.txt do backend):
python backend/database/seed.pyApós o seed, é possível autenticar na tela de login com qualquer um dos usuários abaixo:
| Senha | Papel | |
|---|---|---|
gustavo.admin@vcommerce.com |
admin123 |
admin |
joao.vendas@vcommerce.com |
vendas123 |
sales |
maria.suporte@vcommerce.com |
support123 |
support |
Esses usuários são apenas para ambiente local — não use em produção.
Requer Docker e Docker Compose instalados.
Crie o arquivo backend/.env a partir do exemplo:
# Linux/macOS
cp backend/.env.example backend/.env
# Windows (PowerShell)
Copy-Item backend\.env.example backend\.envEdite backend/.env e preencha apenas a chave da API do Google AI Studio:
GEMINI_API_KEY=sua-chave-aquiImportante: deixe a variável
DATABASE_URLfora do.env(ou remova-a se estiver lá). Oconfig.pyresolve o caminho do banco automaticamente comPath(__file__), e uma URL com caminho absoluto do host vai quebrar dentro do container.
Na raiz do repositório:
docker compose up --buildNa primeira execução o Docker vai baixar as imagens base e instalar as dependências — pode demorar alguns minutos. Nas próximas vezes, você pode subir sem o flag --build somente se não houver mudanças no código ou nas dependências. Sempre que houver alteração de código, Dockerfile, requirements.txt, package.json ou qualquer outra dependência, rode novamente com --build.
docker compose upServiços disponíveis após o boot:
| Serviço | URL |
|---|---|
| Backend | http://localhost:8000 |
| API Docs | http://localhost:8000/docs |
| Frontend | http://localhost:5173 |
Se o banco ainda não foi gerado pelo seed, rode dentro do container do backend:
docker compose exec backend python database/seed.pycurl http://localhost:8000/agent/healthO campo "database" deve retornar "ok". Se retornar "banco não encontrado", repita o passo 3.3.
# Todos os serviços
docker compose logs -f
# Apenas o backend
docker compose logs -f backend
# Apenas o frontend
docker compose logs -f frontend# Para e mantém os containers (sobe rápido depois com `docker compose up`)
docker compose stop
# Para e remove os containers (próximo `up` recria tudo)
docker compose downWindows:
cd backend
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reloadLinux/macOS:
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reloadA API ficará disponível em http://localhost:8000. Documentação interativa em http://localhost:8000/docs.
Requer Node.js v20 LTS ou superior (a imagem oficial usada no Docker é node:20-alpine, então qualquer versão a partir de 20 funciona). Para instalar via CLI:
winget install OpenJS.NodeJS.LTSApós instalar, feche e abra o terminal novamente. Depois:
cd frontend
npm install
npm run devO frontend ficará disponível em http://localhost:5173.
- SQLite foi escolhido como banco local por ser zero-configuração e suficiente para o volume de dados após a agregação na camada Gold. A troca para PostgreSQL exige apenas alterar a connection string no backend.
- Arquitetura Medalhão (Bronze → Silver → Gold) garante rastreabilidade completa dos dados desde a origem bruta até as tabelas analíticas finais.
- Tabelas Gold desnormalizadas eliminam JOINs em tempo de consulta no backend, o que simplifica os endpoints e melhora a performance das queries do agente de IA.
- O arquivo
vcommerce.dbnão é versionado. O banco é sempre gerado localmente a partir dos CSVs viaseed.py.