LJ Velas & Aromas — Documentação
Bem-vindo à documentação técnica da LJ Velas & Aromas. Este é o ponto de partida para qualquer pessoa que desenvolva, mantenha ou integre com o sistema.
O que é este projeto
LJ Velas & Aromas é um e-commerce completo voltado para a venda de velas artesanais e produtos aromáticos, operando em produção em ljvelasearomas.com.br. O projeto foi concebido como uma solução vertical — ou seja, front-end de loja, painel administrativo e API estão todos no mesmo repositório Next.js, compartilhando o mesmo banco de dados e camada de autenticação.
O sistema não utiliza nenhuma plataforma de e-commerce de terceiros (Shopify, VTEX, WooCommerce). Toda a lógica de negócio — carrinho, checkout, pagamentos, emissão de NF-e, frete — é implementada internamente, o que garante flexibilidade total e elimina taxas de plataforma.
Para quem é esta documentação
Esta documentação é destinada a desenvolvedores nas seguintes situações:
| Perfil | Caso de uso principal |
|---|---|
| Desenvolvedor novo no projeto | Entender a arquitetura, rodar localmente e fazer a primeira contribuição |
| Mantenedor do sistema | Diagnosticar incidentes, aplicar migrações e fazer deploys |
| Desenvolvedor de integrações | Consumir a API pública v1 (REST, autenticada por API Key) |
| Auditor técnico | Revisar decisões arquiteturais registradas nos ADRs |
Não é necessário conhecimento prévio do domínio de e-commerce; os conceitos específicos do negócio são explicados ao longo das seções relevantes.
O que o sistema faz
O projeto é composto por três grandes módulos que rodam sob o mesmo processo Next.js:
1. Loja Pública (/)
A vitrine acessível a qualquer visitante, responsável pelo fluxo completo de compra:
- Catálogo de produtos — listagem com filtros por categoria, busca por texto e ordenação por preço/novidade
- Página de produto — galeria de imagens, variações (ex.: tamanho/fragrância), descrição rich-text editável via Puck
- Carrinho — gerenciado por Zustand com persistência em
localStorage; atualização de quantidade, remoção e resumo de pedido - Checkout — endereço de entrega, cálculo de frete (integração com Correios/tabela manual), aplicação de cupons de desconto
- Pagamentos — PIX gerado via MercadoPago SDK (QR Code + copia-e-cola com expiração de 30 min) e cartão de crédito via Stripe Elements
- Confirmação e rastreamento — e-mail transacional com resumo do pedido enviado via Nodemailer/Resend; página
/minha-conta/pedidoscom histórico e status
2. Painel Administrativo (/admin)
Interface protegida por autenticação JWT, acessível apenas a usuários com role ADMIN:
- Gestão de produtos — criação, edição, remoção e controle de estoque por variação
- Gestão de pedidos — visualização de todos os pedidos com filtro por status, atualização de status e disparo de e-mails de notificação
- Gestão de clientes — listagem de clientes, histórico de compras e ações de suporte
- Editor visual Puck — edição de páginas de produto e de conteúdo institucional sem necessidade de deploy
- Cupons de desconto — criação de cupons percentuais ou de valor fixo com data de expiração e limite de uso
- Webhooks — configuração de endpoints externos que recebem eventos de pedido (novo pedido, status atualizado, pagamento confirmado)
- NF-e — integração com serviço
nfe-servicepara emissão de notas fiscais eletrônicas - Relatórios e gráficos — painel com Recharts exibindo receita, pedidos por período e produtos mais vendidos
3. API Pública v1 (/api/v1)
Interface REST documentada, autenticada por API Key enviada no header X-API-Key. Permite que sistemas externos (ERPs, marketplaces, scripts de automação) consultem produtos, criem pedidos e escutem eventos via webhooks.
Status do projeto
| Dimensão | Status |
|---|---|
| Ambiente de produção | ✅ Ativo em ljvelasearomas.com.br |
| Hospedagem | Hostinger (plano Business Hosting + MySQL 8 gerenciado) |
| Deploy | Automático via GitHub Actions (main → Hostinger via SSH/FTP) |
| Monitoramento | HyperDX (OpenTelemetry) + Microsoft Clarity (mapas de calor) |
| Cobertura de testes | Unit/integration com Jest + MSW v2; E2E com Playwright |
| Versão Node.js | 20 LTS (exigência da Hostinger) |
Mapa da documentação
Use a tabela abaixo para navegar diretamente para a seção que você precisa:
| Seção | O que você encontra lá | Quando usar |
|---|---|---|
| Visão Geral / Introdução | Este documento | Primeiro acesso |
| Tech Stack | Tabela de tecnologias, justificativas e diagrama de relacionamento | Antes de contribuir ou avaliar a arquitetura |
| ADRs | Registros de decisões arquiteturais (App Router, Prisma, Zustand, JWT, Rate Limit) | Ao questionar ou revisar uma decisão técnica |
| Arquitetura | Diagrama de componentes, fluxo de dados e separação de responsabilidades | Ao trabalhar em funcionalidades cross-cutting |
| Backend | Rotas de API, middlewares, serviços (pagamento, e-mail, NF-e), models Prisma | Ao implementar ou depurar lógica de servidor |
| Frontend | Componentes, hooks, store Zustand, editor Puck, temas Tailwind | Ao trabalhar na interface da loja ou do admin |
| Infra | Configuração Hostinger, variáveis de ambiente, CI/CD, backup de banco | Ao fazer deploy ou configurar um novo ambiente |
| Guias | Tutoriais passo a passo: adicionar produto, criar cupom, emitir NF-e | Ao onboarding de novos desenvolvedores ou suporte |
| Design | Tokens de design, paleta de cores, tipografia, padrões de componentes | Ao criar novas telas ou ajustar o visual |
Quick Start
Para rodar o projeto localmente em menos de 5 minutos:
# 1. Clone o repositório e instale dependências
git clone https://github.com/seu-usuario/ljvemasearomas.git && cd ljvemasearomas && npm install
# 2. Suba o banco de dados MySQL via Docker e aplique o schema
npm run db:up && npx prisma db push
# 3. Popule o banco com dados de exemplo e inicie o servidor de desenvolvimento
npm run db:seed && npm run dev
Pré-requisitos: Node.js 20 LTS, Docker Desktop em execução e um arquivo
.envpreenchido a partir do.env.example.
O servidor de desenvolvimento estará disponível emhttp://localhost:3000.
Links importantes
| Recurso | URL |
|---|---|
| Repositório GitHub | https://github.com/seu-usuario/ljvemasearomas |
| hPanel Hostinger | https://hpanel.hostinger.com |
| MercadoPago Developers | https://www.mercadopago.com.br/developers |
| Stripe Dashboard | https://dashboard.stripe.com |
| GitHub Actions (CI/CD) | https://github.com/seu-usuario/ljvemasearomas/actions |
| HyperDX (APM) | https://app.hyperdx.io |
| Prisma Studio (local) | npx prisma studio → http://localhost:5555 |