Hero Factory

Aplicação full-stack para gerenciamento de heróis. Crie, edite, desative e ative heróis de diferentes universos como Marvel e DC.

Tecnologias

Backend

• Node.js + TypeScript
• Fastify (servidor HTTP de alta performance)
• Prisma ORM (acesso ao banco de dados com type-safety)
• Zod (validação de schemas)
• MySQL 8.0

Frontend

• Vite + React + TypeScript
• Tailwind CSS + shadcn/ui (componentes acessíveis e estilizados)
• TanStack Query / React Query (gerenciamento de estado do servidor e cache)
• React Hook Form + Zod (formulários com validação)
• Axios (cliente HTTP)

Testes

• Vitest + Supertest

---

Pré-requisitos

• Node.js 18 ou superior
• Docker e Docker Compose
• npm, pnpm ou yarn

---

Configuração e execução

1. Clone o repositório

git clone <url-do-repositorio>
cd web-hero-factory

2. Inicie o banco de dados com Docker

docker compose up -d

Aguarde o container ficar saudável (pode demorar alguns segundos na primeira execução).

3. Configure e inicie a API

cd api
cp .env.example .env
npm install
npm run db:generate   # gera o Prisma Client
npm run db:push       # cria as tabelas no banco
npm run dev           # inicia em modo de desenvolvimento

A API estará disponível em http://localhost:3333.

4. Configure e inicie o frontend

Abra um novo terminal:

cd web
cp .env.example .env
npm install
npm run dev

O frontend estará disponível em http://localhost:5173.

---

Variáveis de ambiente

api/.env

Variável	Descrição	Padrão
DATABASE_URL	URL de conexão MySQL	mysql://root:root@localhost:3306/hero_factory
PORT	Porta da API	3333
FRONTEND_URL	URL do frontend (usada no CORS)	http://localhost:5173

web/.env

Variável	Descrição	Padrão
VITE_API_URL	URL base da API	http://localhost:3333/api

---

Scripts disponíveis

API (api/)

Script	Descrição
npm run dev	Inicia em modo de desenvolvimento com hot reload
npm run build	Compila TypeScript para JavaScript
npm run start	Executa a build compilada
npm run test	Executa os testes unitários
npm run test:coverage	Executa os testes com cobertura
npm run db:generate	Gera o Prisma Client
npm run db:migrate	Cria e aplica uma nova migration
npm run db:push	Sincroniza o schema com o banco (sem migration)
npm run db:seed	Popula o banco com dados de exemplo

Frontend (web/)

Script	Descrição
npm run dev	Inicia em modo de desenvolvimento
npm run build	Gera o build de produção
npm run preview	Visualiza o build de produção localmente
npm run test	Executa os testes

---

Endpoints da API

Método	Rota	Descrição
GET	/api/heroes	Lista heróis (paginado, com busca)
POST	/api/heroes	Cria um novo herói
GET	/api/heroes/:id	Busca um herói por ID
PUT	/api/heroes/:id	Atualiza um herói
DELETE	/api/heroes/:id	Desativa um herói (soft delete)
PATCH	/api/heroes/:id/activate	Reativa um herói

Query params para listagem

Param	Tipo	Padrão	Descrição
page	number	1	Página atual
limit	number	10	Itens por página (máx. 100)
search	string	-	Filtra por nome ou nome de guerra

---

Decisões de arquitetura

Por que Fastify? Fastify é um dos frameworks Node.js mais rápidos disponíveis. Possui suporte nativo a TypeScript, serialização JSON otimizada, sistema de plugins robusto e logging integrado com Pino.

Por que Prisma? Prisma oferece type-safety completo nas queries, migrations automáticas e uma API intuitiva para operações no banco. O Prisma Client é gerado a partir do schema, eliminando discrepâncias entre o código e o banco de dados.

Por que TanStack Query? TanStack Query resolve o problema de gerenciamento de estado assíncrono de forma elegante. Fornece cache automático, revalidação em background, deduplicação de requests e estados de loading/error sem boilerplate manual.

Por que shadcn/ui? shadcn/ui não é uma biblioteca de componentes tradicional — os componentes são copiados diretamente para o projeto, dando controle total sobre o código. Os componentes são construídos sobre Radix UI (acessibilidade garantida) e estilizados com Tailwind CSS.