Task Manager Fullstack (Hexagonal)

Aplicação fullstack de gerenciamento de tarefas construída para demonstrar arquitetura desacoplada, regras de negócio testáveis e fluxo HTTP consistente.

Sumário

• Visão geral
• O que está funcionando
• Stack
• Arquitetura (Hexagonal)
• Estrutura de pastas
• Como clonar o projeto
• Pré-requisitos
• Setup rápido (Docker)
• Setup local (Node + MySQL)
• Variáveis de ambiente
• Como executar
• API (contratos e exemplos)
• Frontend (fluxo funcional)
• Banco de dados
• Testes
• Scripts disponíveis
• Troubleshooting
• Checklist de entrega

Visão geral

O projeto segue o modelo de Ports and Adapters (Hexagonal) no backend:

1. Entrada HTTP (Express)
2. Middlewares (JWT + sanitização)
3. Controller (Zod + mapeamento para DTO)
4. UseCase (regra de negócio)
5. Repository (Prisma + MySQL)
6. Saída padronizada + Global Error Handler

O que está funcionando

Backend

• Autenticação JWT via POST /api/auth/login com userId.
• Middleware de autenticação para proteger rotas de tarefas.
• Middleware de sanitização básica (trim, remoção de < e >).
• CRUD de tarefas completo:
  • Criar em lote (até 1000 registros)
  • Listar tarefas do usuário autenticado
  • Buscar por id
  • Atualizar (title, description, status)
  • Excluir
• Regra de segurança: apenas o dono pode acessar/editar/excluir a própria task.
• Tratamento global de erros com mapeamento de erros de domínio para HTTP.

Frontend

• Login por userId para obtenção de JWT.
• Criação em lote (uma task por linha).
• Listagem de tarefas do usuário logado.
• Atualização de status (PENDING/DONE) com toggle.
• Edição inline de título (Salvar/Cancelar).
• Exclusão de tarefa.

Qualidade

• TypeScript em modo estrito.
• Testes unitários no backend (camada de comunicação + use cases).
• Build de backend e frontend funcionando.
• Docker Compose para MySQL + backend.

Stack

• Linguagem: TypeScript (strict)
• Backend: Express, Zod, JWT
• ORM/Banco: Prisma + MySQL
• Frontend: React + Vite
• Testes: Jest

Arquitetura (Hexagonal)

Camadas

• Domain: entidades e erros de domínio
• Application: use cases + ports (interfaces)
• Adapters (Input/Output): controllers/middlewares/routes + repository Prisma
• Infrastructure/Main: wiring de dependências, client Prisma, bootstrap do app

Princípios aplicados

• Use cases dependem de interfaces, não de Prisma/Express.
• Controllers validam schema com Zod e apenas orquestram entrada/saída.
• Regras de autorização por dono ficam protegidas na camada de aplicação.
• Erros de domínio são traduzidos para status HTTP no handler global.

Documento auxiliar de arquitetura: apps/backend/ARCHITECTURE.md.

Estrutura de pastas

apps/
  backend/
    prisma/
    src/
      domain/
      application/
      adapters/
      infrastructure/
      main/
  frontend/
    src/
docker-compose.yml

Como clonar o projeto

Opção 1: HTTPS

git clone https://github.com/GabrielaMoura25/Task-Manager-.git
cd Task-Manager-

Opção 2: SSH

git clone git@github.com:GabrielaMoura25/Task-Manager-.git
cd Task-Manager-

Pré-requisitos

• Node.js 20+
• npm 10+
• Docker + Docker Compose (recomendado)

Setup rápido (Docker)

Sobe MySQL e backend de uma vez:

docker compose up -d --build

O docker-compose.yml lê as variáveis do arquivo apps/backend/.env via env_file, evitando hardcode de credenciais no YAML.

Serviços:

• API: http://localhost:3000
• MySQL para cliente externo: 127.0.0.1:3310
• MySQL interno (containers): mysql:3306

Parar tudo:

docker compose down

Setup local (Node + MySQL)

1. Instale dependências:

npm install

2. Configure .env:

cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env

3. Ajuste DATABASE_URL em apps/backend/.env conforme seu cenário:

# MySQL instalado localmente
DATABASE_URL="mysql://root:root@localhost:3306/medcof_tasks"

# MySQL vindo do docker-compose (porta publicada 3310)
DATABASE_URL="mysql://root:root@localhost:3310/medcof_tasks"

MYSQL_ROOT_PASSWORD="root"
MYSQL_DATABASE="medcof_tasks"
MYSQL_USER="root"

4. Gere o Prisma Client e sincronize o banco:

npm run prisma:generate --workspace @medcof/backend
npm run prisma:push --workspace @medcof/backend

Variáveis de ambiente

Backend (apps/backend/.env)

DATABASE_URL="mysql://root:root@localhost:3306/medcof_tasks"
JWT_SECRET="change-me"
PORT=3000
MYSQL_ROOT_PASSWORD="root"
MYSQL_DATABASE="medcof_tasks"
MYSQL_USER="root"

Frontend (apps/frontend/.env)

VITE_API_BASE_URL="http://localhost:3000/api"

Como executar

Backend

npm run dev:backend

Frontend

npm run dev:frontend

Build completo

npm run build

API (contratos e exemplos)

Base URL: http://localhost:3000/api

1) Login

POST /auth/login

Body:

{
  "userId": "user-a"
}

Resposta (200):

{
  "success": true,
  "data": {
    "token": "<JWT>"
  }
}

2) Criar tarefas em lote

POST /tasks

Headers:

• Authorization: Bearer <JWT>

Body:

{
  "tasks": [
    { "title": "Task 1" },
    { "title": "Task 2", "description": "Descrição opcional" }
  ]
}

Resposta (201):

{
  "success": true,
  "data": {
    "createdCount": 2
  }
}

3) Listar tarefas

GET /tasks

Resposta (200):

{
  "success": true,
  "data": [
    {
      "id": "...",
      "ownerId": "user-a",
      "title": "Task 1",
      "description": null,
      "status": "PENDING",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ]
}

4) Buscar por id

GET /tasks/:id

5) Atualizar tarefa

PATCH /tasks/:id

Body (exemplo):

{
  "title": "Novo título",
  "status": "DONE"
}

6) Excluir tarefa

DELETE /tasks/:id

Resposta (200):

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Códigos de erro relevantes

• 400 REQUEST_VALIDATION_ERROR
• 400 BULK_LIMIT_EXCEEDED
• 401 UNAUTHORIZED
• 403 FORBIDDEN_TASK_ACCESS
• 404 TASK_NOT_FOUND
• 500 INTERNAL_SERVER_ERROR

Frontend (fluxo funcional)

1. Informar userId e gerar JWT.
2. Criar tasks em lote (uma por linha).
3. Atualizar lista.
4. Editar título inline.
5. Alternar status e excluir.

Banco de dados

Schema Prisma atual (Task):

• id (cuid)
• ownerId
• title
• description (nullable)
• status (PENDING | DONE)
• createdAt
• updatedAt
• índice em ownerId

Testes

Executar testes do backend:

npm test

Escopo atual coberto:

• Use case de criação em lote (limites e sucesso com mock de repositório)
• Use case de acesso por id (not found, forbidden, sucesso)
• Controller (validação e mapeamento para DTO)
• Middleware JWT
• Global Error Handler

Scripts disponíveis

Raiz

• npm run dev:backend
• npm run dev:frontend
• npm run build
• npm test

Backend

• npm run dev --workspace @medcof/backend
• npm run build --workspace @medcof/backend
• npm run test --workspace @medcof/backend
• npm run prisma:generate --workspace @medcof/backend
• npm run prisma:migrate --workspace @medcof/backend
• npm run prisma:migrate:deploy --workspace @medcof/backend
• npm run prisma:push --workspace @medcof/backend

Frontend

• npm run dev --workspace @medcof/frontend
• npm run build --workspace @medcof/frontend
• npm run preview --workspace @medcof/frontend

Troubleshooting

DBeaver: Public Key Retrieval is not allowed

No driver MySQL, configure:

• allowPublicKeyRetrieval=true
• useSSL=false

Ou use URL:

jdbc:mysql://127.0.0.1:3310/medcof_tasks?allowPublicKeyRetrieval=true&useSSL=false

Erro de conexão no DBeaver

• Verifique se o compose está no ar: docker compose ps
• Confirme porta 3310 publicada para MySQL
• Host correto: 127.0.0.1 (não mysql)

Backend no Docker sem tabela

Se necessário, sincronize manualmente:

docker compose exec backend npm run prisma:push

Checklist de entrega

• TypeScript strict no backend/frontend
• Backend em Express
• Frontend em React
• Prisma + MySQL
• Arquitetura hexagonal no backend
• JWT + sanitização em middleware
• Validação com Zod em controllers
• Use cases desacoplados por interfaces (ports)
• Global Error Handler
• Segurança de ownership por task
• Criação em lote até 1000 registros
• Testes unitários (comunicação + use cases)
• README com setup/execução/testes

---