🧩 Customer Management Web

MVP de gerenciamento de clientes com autenticação avançada, editor SQL integrado e painel de configurações completo.

---

📋 Sobre o projeto

Customer Management Web é um MVP para gerenciamento de clientes, construído com as melhores práticas de arquitetura frontend moderna. O projeto serve como base sólida para sistemas de gestão, com foco em autenticação robusta, UI acessível e organização de código escalável.

✨ Funcionalidades

• 📋 CRUD de Clientes — listagem, criação, edição e remoção com tabela interativa (PF e PJ)
• 🔐 Autenticação completa via Better Auth
  • Login com e-mail e senha
  • OAuth social (Google, GitHub)
  • Autenticação de dois fatores (TOTP + códigos de backup)
  • Passkeys (WebAuthn / FIDO2)
• 🖥️ Editor SQL integrado com CodeMirror e syntax highlighting
• 👥 Gerenciamento de usuários (admin) com banimento e controle de papéis
• 📊 Módulo de análise com gráficos interativos e cards de métricas
• 📣 Marketing por e-mail — campanhas segmentadas por público (PF, PJ ou todos), com envio em lote via Resend, painel de aniversariantes e histórico de envios
• 👤 Painel de configurações com abas para:
  • Perfil (nome e e-mail)
  • Segurança (troca de senha)
  • Autenticação 2FA
  • Passkeys
  • Contas sociais
  • Sessões ativas
• 🌙 Tema claro/escuro com next-themes
• 📧 Envio de e-mails transacionais via Resend

---

🛠️ Stack tecnológica

Frontend

Tecnologia	Versão	Uso
Next.js	16.2	Framework React com App Router
React	19	UI library
TypeScript	5	Tipagem estática
TailwindCSS	4	Estilização utility-first
Shadcn UI	4.7	Componentes acessíveis
Radix UI	1.4	Primitivos de UI
TanStack Query	5	Cache e estado de servidor
TanStack Table	8	Tabelas headless
React Hook Form	7	Gerenciamento de formulários
Zod	4	Validação de schemas
Lucide React	1.11	Ícones
Sonner	2	Notificações toast
Motion	12	Animações
CodeMirror	6	Editor de código/SQL
Recharts	3.8	Gráficos
dnd-kit	6	Drag and drop

Backend / Infra

Tecnologia	Versão	Uso
Prisma ORM	7	Acesso ao banco de dados
PostgreSQL	16	Banco de dados relacional
Better Auth	1.6	Autenticação completa
Resend	6	Envio de e-mails
Docker	—	Ambiente de banco de dados
SimpleWebAuthn	13	Passkeys / WebAuthn

Qualidade de código

Modelos principais (Prisma)

Modelo	Descrição
Cliente	Pessoa Física ou Jurídica com endereço e contatos
User / Session / Account	Autenticação via Better Auth
TwoFactor / Passkey	2FA e WebAuthn
QueryLog	Histórico de queries executadas no SQL console
Campaign / CampaignSend	Campanhas de e-mail marketing e registros de envio

---

🔍 Qualidade de código

• ESLint — linting com regras para Next.js e TanStack Query
• Prettier — formatação consistente
• TypeScript strict — tipagem rigorosa em todo o projeto

---

🏗️ Arquitetura

O projeto segue uma arquitetura modular por feature (inspirada em Clean Architecture), separando responsabilidades em camadas bem definidas:

src/
├── app/                          # Rotas Next.js (App Router)
│   ├── (auth)/                   # Sign-in, sign-up, forgot/reset-password, verify-email
│   └── (dashboard)/              # Área autenticada (AppSidebar + SiteHeader)
│       ├── dashboard/            # Módulo de análise
│       ├── clients/              # CRUD de clientes (lista, novo, editar, detalhe)
│       ├── marketing/            # Módulo de e-mail marketing
│       ├── settings/             # Painel de configurações
│       └── (admin)/admin/        # Área admin (SQL console, gerenciamento de usuários)
├── components/                   # Componentes globais reutilizáveis
│   └── ui/                       # Design system (Shadcn UI)
├── modules/                      # Features da aplicação
│   ├── auth/                     # Autenticação (login, cadastro, 2FA, passkeys)
│   ├── clients/                  # CRUD de clientes PF/PJ
│   ├── admin/                    # SQL console + gerenciamento de usuários
│   ├── profile/                  # Configurações de conta e segurança
│   ├── analysis/                 # Dashboard com gráficos e métricas
│   └── marketing/                # Campanhas de e-mail marketing
├── actions/                      # Server Actions (client, admin, marketing)
├── schemas/                      # Schemas Zod de validação
├── types/                        # Tipos globais compartilhados
└── lib/                          # Configurações globais (auth, prisma, email)

Cada módulo segue o padrão:

modules/<feature>/
├── index.ts              # Re-exports de views
├── types/index.ts        # Tipos específicos da feature
├── hooks/                # useQuery / useMutation isolados
└── ui/
    ├── views/            # Componentes de página (consumidos pelo app/)
    └── components/       # Sub-componentes com responsabilidade única

---

🚀 Rodando localmente

Pré-requisitos

• Node.js >= 20
• pnpm >= 9 (npm install -g pnpm)
• Docker e Docker Compose

1. Clone o repositório

git clone https://github.com/Cardosofiles/customer-management-web.git
cd customer-management-web

2. Instale as dependências

pnpm install

3. Configure as variáveis de ambiente

cp .env.example .env

Edite o .env com seus valores:

# PostgreSQL (Docker)
POSTGRES_CONTAINER_NAME=customer-management-db
POSTGRES_PORT=5432
POSTGRES_DB=customer_management
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_PGDATA=/data/postgres

# PgAdmin (opcional)
PGADMIN_CONTAINER_NAME=customer-management-pgadmin
PGADMIN_PORT=5050
PGADMIN_DEFAULT_EMAIL=admin@admin.com
PGADMIN_DEFAULT_PASSWORD=admin

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/customer_management

# Better Auth
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=  # gere com: openssl rand -base64 32

# Resend (e-mail)
RESEND_API_KEY=re_xxxxxxxxxxxx
RESEND_FROM=noreply@seudominio.com

# Seed
SEED_ADMIN_EMAIL=admin@example.com
SEED_ADMIN_PASSWORD=Admin@123456

# OAuth (opcional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

4. Suba o banco de dados

docker compose up -d

PgAdmin disponível em http://localhost:5050

5. Execute as migrations e gere o client Prisma

pnpm db:generate
pnpm db:migrate

6. (Opcional) Execute o seed

pnpm db:seed

7. Inicie a aplicação

pnpm dev

Acesse em http://localhost:3000 🎉

---

📜 Scripts disponíveis

Comando	Descrição
pnpm dev	Inicia em modo desenvolvimento
pnpm build	Gera build de produção
pnpm start	Inicia o servidor de produção
pnpm lint	Executa o ESLint
pnpm db:generate	Gera o Prisma Client
pnpm db:migrate	Executa migrations de desenvolvimento
pnpm db:studio	Abre o Prisma Studio
pnpm db:seed	Popula o banco com dados iniciais

---

🔐 Configurando OAuth (opcional)

Google

1. Acesse Google Cloud Console
2. Crie um projeto e vá em APIs & Services → Credentials
3. Crie um OAuth 2.0 Client ID com redirect URI: http://localhost:3000/api/auth/callback/google
4. Copie GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET

GitHub

1. Acesse GitHub Developer Settings
2. Crie um OAuth App com callback URL: http://localhost:3000/api/auth/callback/github
3. Copie GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET

---

👨‍💻 Desenvolvedor

Joao Batista Cardoso Miranda

Front-end Engineer · SaaS Builder

---

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

---

_{Feito com ☕ e TypeScript · Uberlândia, MG 🇧🇷}