🧠 TaskMind

SaaS de gestão de projetos inspirado no Jira, com foco em clareza, simplicidade e IA como copiloto

📋 Índice

Sobre o Projeto
Features
Tecnologias
Arquitetura
Pré-requisitos
Instalação
Configuração
Uso
Scripts Disponíveis
Estrutura do Projeto
API
Desenvolvimento
Testes
Deploy
Troubleshooting
Contribuindo
Roadmap
Licença

🎯 Sobre o Projeto

TaskMind é uma plataforma SaaS moderna para gestão de projetos e issues, desenvolvida com foco em:

Clareza: Interface intuitiva com baixa carga cognitiva
Simplicidade: Menos campos, mais inteligência
IA Copiloto: Assistente inteligente para criação e gestão de issues
Multi-tenant: Suporte completo a múltiplas organizações
RBAC: Controle de acesso baseado em roles
Audit Log: Rastreabilidade completa de todas as ações

✨ Features

Core

✅ Gestão de Projetos: Criação e organização de projetos por organização
✅ Kanban Board: Visualização e gestão de issues em formato Kanban
✅ Backlog: Lista de issues com filtros avançados
✅ Workflows Customizáveis: Definição de estados e transições personalizadas
✅ Sprints: Planejamento e gestão de sprints
✅ Comentários: Sistema de comentários em issues

Autenticação & Segurança

✅ JWT Authentication: Access tokens e refresh tokens
✅ RBAC: Role-Based Access Control (Admin, Member, Viewer)
✅ Multi-tenant: Isolamento completo por organização
✅ Rate Limiting: Proteção contra abuso de API
✅ Audit Log: Registro completo de todas as ações

IA Copiloto

✅ Enhance Description: Melhora descrições de issues usando IA
✅ Breakdown Tasks: Sugere subtarefas a partir de descrições
✅ Smart Suggestions: Sugestões inteligentes de prioridade e tipo

Frontend

✅ Next.js 14 App Router: Framework moderno com SSR
✅ Tailwind CSS: Estilização utilitária
✅ Drag & Drop: Reordenação de issues no Kanban
✅ Responsive Design: Interface adaptável a diferentes telas

🛠 Tecnologias

Backend

Runtime: Node.js 18+
Framework: Express.js
Language: TypeScript 5.3
ORM: Prisma 5.7
Database: PostgreSQL 15
Auth: JWT (jsonwebtoken)
Validation: Zod
Logging: Winston
API Docs: Swagger/OpenAPI

Frontend

Framework: Next.js 14 (App Router)
Language: TypeScript 5.3
Styling: Tailwind CSS 3.4
Icons: Heroicons
Drag & Drop: @dnd-kit
Sanitization: DOMPurify

DevOps & Tools

Monorepo: npm workspaces
Container: Docker & Docker Compose
Linting: ESLint + Prettier
Git Hooks: Husky + lint-staged
Testing: Vitest

🏗 Arquitetura

Visão Geral

┌─────────────────────────────────────────────────────────┐
│                    TaskMind Monorepo                     │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────┐  │
│  │   apps/web   │    │   apps/api   │    │ packages │  │
│  │  (Next.js)   │◄──►│  (Express)   │◄──►│  shared  │  │
│  │              │    │              │    │          │  │
│  │  Port 3000   │    │  Port 3001   │    │  Types   │  │
│  └──────┬───────┘    └──────┬───────┘    │  DTOs    │  │
│         │                    │            │  Utils   │  │
│         │                    │            └──────────┘  │
│         │                    │                          │
│         └────────────────────┴──────────────────────┐   │
│                                                      │   │
│  ┌──────────────────────────────────────────────────┘   │
│  │                                                      │
│  ▼                                                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │         PostgreSQL (Docker)                      │  │
│  │         Port 5432                                │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Estrutura de Camadas (Backend)

apps/api/src/
├── controllers/     # Camada de apresentação (HTTP handlers)
├── services/        # Camada de lógica de negócio
├── middleware/      # Middlewares (auth, error handling, etc)
├── routes/          # Definição de rotas
├── config/          # Configurações (DB, env, swagger)
└── utils/           # Utilitários e helpers

Estrutura de Camadas (Frontend)

apps/web/src/
├── app/             # Next.js App Router (pages)
├── components/      # Componentes React
│   ├── ui/         # Componentes base reutilizáveis
│   ├── layout/     # Componentes de layout
│   ├── board/      # Componentes do Kanban
│   └── issues/     # Componentes de issues
└── lib/            # Utilitários e services

📦 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

Node.js >= 18.0.0 (Download)
npm >= 9.0.0 (vem com Node.js)
Docker e Docker Compose (Download)
Git (Download)

Verificação

node --version  # Deve ser >= 18.0.0
npm --version   # Deve ser >= 9.0.0
docker --version
docker compose version

🚀 Instalação

1. Clonar o Repositório

git clone <repo-url>
cd TaskMind

2. Instalar Dependências

npm install

Este comando instalará as dependências de todos os workspaces (apps e packages).

3. Configurar Variáveis de Ambiente

Backend (`apps/api/.env`)

cp apps/api/.env.example apps/api/.env

Edite o arquivo .env com suas configurações:

# Database
DATABASE_URL="postgresql://taskmind:taskmind_dev@localhost:5432/taskmind?schema=public"

# JWT
JWT_SECRET="seu-secret-super-seguro-minimo-32-caracteres-aqui"
JWT_EXPIRES_IN="7d"
JWT_REFRESH_EXPIRES_IN="30d"

# Server
PORT=3001
NODE_ENV=development

# CORS
CORS_ORIGIN="http://localhost:3000"

# OpenAI (opcional - para IA Copiloto)
OPENAI_API_KEY="sk-..."

Frontend (`apps/web/.env`)

cp apps/web/.env.example apps/web/.env

Edite o arquivo .env:

NEXT_PUBLIC_API_URL=http://localhost:3001/api

4. Subir o Banco de Dados

npm run docker:up

Isso iniciará um container PostgreSQL na porta 5432.

5. Executar Migrações

npm run db:migrate

Este comando:

Gera o Prisma Client
Executa as migrações do banco de dados
Cria todas as tabelas necessárias

6. Popular o Banco (Opcional)

npm run db:seed

Isso criará dados de exemplo para desenvolvimento.

🎮 Uso

Desenvolvimento

Opção 1: Rodar tudo junto

npm run dev:all

Opção 2: Rodar separadamente (recomendado)

Terminal 1 - API:

npm run dev:api

Terminal 2 - Frontend:

npm run dev:web

Acessar a Aplicação

Frontend: http://localhost:3000
API: http://localhost:3001
API Docs (Swagger): http://localhost:3001/api-docs
Prisma Studio: Execute npm run db:studio e acesse http://localhost:5555

Credenciais Padrão (após seed)

Email: admin@taskmind.demo
Senha: admin123

📜 Scripts Disponíveis

Raiz do Monorepo

Desenvolvimento

npm run dev              # Roda todos os workspaces em dev
npm run dev:api          # Roda apenas a API
npm run dev:web          # Roda apenas o Web
npm run dev:all          # Roda API e Web em paralelo

Build

npm run build            # Build de todos os workspaces
npm run build:api        # Build apenas da API
npm run build:web        # Build apenas do Web

Docker

npm run docker:up        # Sobe container PostgreSQL
npm run docker:down      # Para e remove container
npm run docker:logs      # Mostra logs do PostgreSQL

Banco de Dados

npm run db:migrate       # Executa migrações Prisma
npm run db:studio        # Abre Prisma Studio (GUI)
npm run db:seed          # Popula banco com dados de exemplo

Qualidade de Código

npm run lint             # Lint em todos os workspaces
npm run lint:fix         # Lint + auto-fix
npm run format           # Formata código com Prettier
npm run format:check     # Verifica formatação (CI)
npm run type-check       # Type-check em todos os workspaces

Utilitários

npm run clean            # Remove node_modules e builds

Apps/API

cd apps/api

npm run dev              # Desenvolvimento com hot reload (tsx watch)
npm run build            # Compila TypeScript
npm start                # Roda versão compilada
npm run test             # Executa testes (Vitest)
npm run test:watch       # Testes em modo watch
npm run test:coverage    # Testes com cobertura
npm run prisma:generate  # Gera Prisma Client
npm run prisma:migrate   # Cria/applica migrações
npm run prisma:studio    # Abre Prisma Studio
npm run prisma:seed      # Popula banco

Apps/Web

cd apps/web

npm run dev              # Desenvolvimento Next.js
npm run build            # Build de produção
npm start                # Roda build de produção
npm run lint             # Lint Next.js
npm run type-check       # Type-check TypeScript

📁 Estrutura do Projeto

TaskMind/
├── apps/
│   ├── api/                    # Backend API
│   │   ├── prisma/             # Schema e migrações
│   │   │   ├── schema.prisma  # Schema do banco
│   │   │   ├── seed.ts        # Script de seed
│   │   │   └── migrations/     # Migrações do Prisma
│   │   ├── src/
│   │   │   ├── config/        # Configurações (DB, env, swagger)
│   │   │   ├── controllers/   # HTTP handlers
│   │   │   ├── services/      # Lógica de negócio
│   │   │   ├── middleware/    # Middlewares (auth, errors, etc)
│   │   │   ├── routes/        # Definição de rotas
│   │   │   ├── utils/         # Utilitários
│   │   │   └── index.ts       # Entry point
│   │   ├── .env.example       # Exemplo de variáveis de ambiente
│   │   └── package.json
│   │
│   └── web/                    # Frontend Next.js
│       ├── src/
│       │   ├── app/           # Next.js App Router
│       │   │   ├── layout.tsx
│       │   │   ├── page.tsx
│       │   │   ├── login/
│       │   │   ├── register/
│       │   │   └── project/[projectId]/
│       │   ├── components/    # Componentes React
│       │   │   ├── ui/        # Componentes base
│       │   │   ├── layout/   # Layout components
│       │   │   ├── board/    # Kanban components
│       │   │   └── issues/   # Issue components
│       │   └── lib/          # Utilitários e services
│       ├── public/           # Assets estáticos
│       ├── .env.example
│       └── package.json
│
├── packages/
│   └── shared/               # Package compartilhado
│       ├── src/
│       │   ├── dto/         # Data Transfer Objects
│       │   ├── enums/       # Enums compartilhados
│       │   ├── types/       # Tipos TypeScript
│       │   ├── utils/       # Utilitários (filters, validation)
│       │   └── constants/   # Constantes
│       └── package.json
│
├── docker-compose.yml        # Configuração PostgreSQL
├── package.json             # Workspace root
├── .eslintrc.js            # Config ESLint
├── .prettierrc             # Config Prettier
├── .husky/                 # Git hooks
└── README.md

🔌 API

Autenticação

A API usa JWT com access tokens (vida curta) e refresh tokens (vida longa).

Registrar Usuário

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "senha123",
  "name": "João Silva",
  "organizationName": "Minha Empresa",
  "organizationSlug": "minha-empresa"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "senha123"
}

Resposta:

{
  "success": true,
  "data": {
    "user": { ... },
    "accessToken": "eyJ...",
    "refreshToken": "eyJ..."
  }
}

Usar Token

GET /api/projects
Authorization: Bearer <accessToken>

Refresh Token

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJ..."
}

Endpoints Principais

Auth: /api/auth/* - Autenticação e registro
Organizations: /api/orgs/* - Gestão de organizações
Projects: /api/projects/* - Gestão de projetos
Issues: /api/issues/* - Gestão de issues
Workflows: /api/workflows/* - Gestão de workflows
AI: /api/ai/* - Endpoints de IA Copiloto

Documentação Completa

Acesse a documentação interativa no Swagger UI:

URL: http://localhost:3001/api-docs
Documentação: Veja apps/api/API_DOCS.md

💻 Desenvolvimento

Convenções de Código

TypeScript: Tipagem estrita habilitada
ESLint: Regras configuradas para TypeScript
Prettier: Formatação automática
Conventional Commits: Padrão de mensagens de commit

Git Hooks

O projeto usa Husky para executar hooks antes de commits:

Pre-commit: Executa lint-staged (lint + format)
Apenas arquivos staged são verificados

Estrutura de Commits

Siga o padrão Conventional Commits:

feat: adiciona nova feature
fix: corrige bug
docs: atualiza documentação
style: formatação de código
refactor: refatoração
test: adiciona testes
chore: tarefas de manutenção

Workflow de Desenvolvimento

Criar branch: git checkout -b feat/nova-feature
Desenvolver: Fazer alterações
Testar: npm run test (quando aplicável)
Lint: npm run lint:fix
Commit: git commit -m "feat: descrição"
Push: git push origin feat/nova-feature
Pull Request: Criar PR no repositório

Hot Reload

Backend: Usa tsx watch para hot reload automático
Frontend: Next.js tem hot reload nativo

🧪 Testes

Backend

cd apps/api
npm run test              # Executa todos os testes
npm run test:watch         # Modo watch
npm run test:coverage      # Com cobertura

Estrutura de Testes

apps/api/src/
├── services/
│   └── __tests__/        # Testes unitários
│       └── aiService.test.ts
└── utils/
    └── __tests__/
        └── diff.test.ts

Frontend

Testes do frontend podem ser adicionados usando:

Vitest (recomendado)
React Testing Library
Jest

🚢 Deploy

Pré-requisitos para Produção

Variáveis de Ambiente: Configure todas as variáveis necessárias
Database: PostgreSQL em produção (não use Docker em prod)
Build: Execute npm run build em ambos os apps
Migrações: Execute npm run db:migrate antes de iniciar

Backend (API)

cd apps/api
npm run build
npm start

Ou usando PM2:

pm2 start dist/index.js --name taskmind-api

Frontend (Web)

cd apps/web
npm run build
npm start

Ou usando PM2:

pm2 start npm --name taskmind-web -- start

Docker (Produção)

Crie um Dockerfile para cada app e use docker-compose.prod.yml:

version: '3.8'
services:
  api:
    build: ./apps/api
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
    # ...
  
  web:
    build: ./apps/web
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=${API_URL}
    # ...

🔍 Troubleshooting

Problemas Comuns

API não conecta no banco

Verifique se PostgreSQL está rodando:
```
npm run docker:logs
```
Verifique DATABASE_URL no .env da API
Verifique credenciais no docker-compose.yml
Teste conexão:
```
npm run db:studio
```

Porta já em uso

API (3001): Altere PORT no .env da API
Web (3000): Altere no package.json do web: "dev": "next dev -p 3001"
PostgreSQL (5432): Altere no docker-compose.yml

Solução rápida (Windows):

# Matar processo na porta 3001
cd apps/api
npm run kill-port 3001

Erro de workspace

# Limpar tudo
npm run clean
npm install

Erro de migração Prisma

# Resetar banco (CUIDADO: apaga dados)
cd apps/api
npx prisma migrate reset

# Ou criar nova migração
npm run prisma:migrate

Erro de build TypeScript

# Verificar erros de tipo
npm run type-check

# Limpar e rebuild
npm run clean
npm install
npm run build

CORS Error

Verifique CORS_ORIGIN no .env da API. Deve corresponder à URL do frontend.

Token JWT inválido

Verifique JWT_SECRET no .env da API
Certifique-se de que o secret tem pelo menos 32 caracteres
Limpe cookies/localStorage e faça login novamente

🤝 Contribuindo

Contribuições são bem-vindas! Siga estes passos:

Fork o projeto
Crie uma branch (git checkout -b feat/AmazingFeature)
Commit suas mudanças (git commit -m 'feat: Add AmazingFeature')
Push para a branch (git push origin feat/AmazingFeature)
Abra um Pull Request

Guidelines

Siga as convenções de código
Adicione testes para novas features
Atualize a documentação quando necessário
Mantenha commits pequenos e focados

🗺 Roadmap

Próximas Features

Melhorias Técnicas

Cache: Implementar Redis para cache
Queue: Sistema de filas para tarefas assíncronas
Monitoring: Integração com Sentry/DataDog
CI/CD: Pipeline completo de CI/CD
Documentation: Melhorar documentação da API
Performance: Otimizações de performance
Security: Auditoria de segurança

📚 Documentação Adicional

API Documentation - Documentação completa da API
AI Copilot Guide - Guia do IA Copiloto
Frontend README - Documentação do frontend
Design System - Sistema de design
Database Schema - Schema do banco
Shared Package - Documentação do package shared

📄 Licença

👥 Autores

Desenvolvido com ❤️ pela equipe TaskMind

🙏 Agradecimentos

Next.js - Framework React
Prisma - ORM moderno
Express - Framework Node.js
Tailwind CSS - Framework CSS
E todas as outras bibliotecas open-source que tornam este projeto possível

Feito com ❤️ usando TypeScript, Next.js e Express

⬆ Voltar ao topo

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.husky		.husky
apps		apps
packages/shared		packages/shared
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.lintstagedrc.js		.lintstagedrc.js
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

🧠 TaskMind

📋 Índice

🎯 Sobre o Projeto

✨ Features

Core

Autenticação & Segurança

IA Copiloto

Frontend

🛠 Tecnologias

Backend

Frontend

DevOps & Tools

🏗 Arquitetura

Visão Geral

Estrutura de Camadas (Backend)

Estrutura de Camadas (Frontend)

📦 Pré-requisitos

Verificação

🚀 Instalação

1. Clonar o Repositório

2. Instalar Dependências

3. Configurar Variáveis de Ambiente

Backend (apps/api/.env)

Frontend (apps/web/.env)

4. Subir o Banco de Dados

5. Executar Migrações

6. Popular o Banco (Opcional)

🎮 Uso

Desenvolvimento

Opção 1: Rodar tudo junto

Opção 2: Rodar separadamente (recomendado)

Acessar a Aplicação

Credenciais Padrão (após seed)

📜 Scripts Disponíveis

Raiz do Monorepo

Desenvolvimento

Build

Docker

Banco de Dados

Qualidade de Código

Utilitários

Apps/API

Apps/Web

📁 Estrutura do Projeto

🔌 API

Autenticação

Registrar Usuário

Login

Usar Token

Refresh Token

Endpoints Principais

Documentação Completa

💻 Desenvolvimento

Convenções de Código

Git Hooks

Estrutura de Commits

Workflow de Desenvolvimento

Hot Reload

🧪 Testes

Backend

Estrutura de Testes

Frontend

🚢 Deploy

Pré-requisitos para Produção

Backend (API)

Frontend (Web)

Docker (Produção)

🔍 Troubleshooting

Problemas Comuns

API não conecta no banco

Porta já em uso

Erro de workspace

Erro de migração Prisma

Erro de build TypeScript

CORS Error

Token JWT inválido

Backend (`apps/api/.env`)

Frontend (`apps/web/.env`)

Packages