TaskForge

Kanban-style project management platform with real-time collaboration, REST API, CLI client, and React dashboard.

---

Badges

---

English

Overview

TaskForge is a full-stack task management application built with a RESTful API backend in Express + TypeScript, a React + Vite dashboard, and a CLI client for terminal usage. It supports real-time collaboration via WebSockets, full-text search with PostgreSQL tsvector, JWT authentication, and activity audit logging.

Features

• User authentication — register, login, refresh tokens (JWT access + refresh)
• Card management — create, read, update, delete cards with optimistic concurrency (version field)
• Full-text search — powered by PostgreSQL tsvector with Spanish language support
• Labels — create, assign, and unassign labels to cards
• Activity log — audit trail of all mutations with actor, action, entity type, and metadata
• Real-time events — WebSocket server broadcasts card.created, card.updated, card.deleted, card.moved events
• Reordering — move cards between lists with position tracking
• Dashboard — React + Vite SPA with dark theme, login/register, card search, create, and delete
• CLI — terminal client to login, list, create, move, and search cards
• CI — GitHub Actions workflow running tests on Node 20 and 22

Tech Stack

Layer	Technology
Backend	Express 5, TypeScript 6, Node 22
Database	PostgreSQL (via pg pool)
Auth	JWT (access + refresh tokens), bcryptjs
Real-time	WebSocket (ws library)
Frontend	React 19, Vite 8, TypeScript 6
CLI	TypeScript, fetch API
Testing	Vitest 4, Supertest
CI/CD	GitHub Actions

Getting Started

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Fill in DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

# Seed the database with demo Kanban data
npm run db:seed

# Start development server
npm run dev

# Run tests
npm run test:run

# Start dashboard (separate terminal)
cd dashboard && npm install && npm run dev

Demo Credentials

After seeding, you can log into the dashboard using:

• Email: demo@taskforge.com
• Password: password123

API Endpoints

Method	Path	Auth	Description
POST	/auth/register	No	Register new user
POST	/auth/login	No	Login
POST	/auth/refresh	No	Refresh access token
GET	/health	No	Health check
GET	/api/ping	No	Ping
GET	/api/ping/me	Yes	Auth check
GET	/api/lists/:listId/cards	Yes	List cards in a list
POST	/api/lists/:listId/cards	Yes	Create card
GET	/api/cards/:id	Yes	Get card by id
PATCH	/api/cards/:id	Yes	Update card
DELETE	/api/cards/:id	Yes	Delete card
POST	/api/cards/:id/move	Yes	Move card to another list
GET	/api/cards/search?q=	Yes	Full-text search
POST	/api/labels	Yes	Create label
GET	/api/labels	Yes	List all labels
POST	/api/cards/:cardId/labels/:labelId	Yes	Assign label
DELETE	/api/cards/:cardId/labels/:labelId	Yes	Unassign label

---

Español

Resumen

TaskForge es una aplicación full-stack de gestión de tareas con una API REST en Express + TypeScript, un dashboard en React + Vite y un CLI para terminal. Soporta colaboración en tiempo real via WebSockets, búsqueda de texto completo con PostgreSQL tsvector, autenticación JWT y registro de auditoría de actividades.

Características

• Autenticación de usuarios — registro, inicio de sesión, renovación de tokens (JWT access + refresh)
• Gestión de tarjetas — crear, leer, actualizar, eliminar tarjetas con concurrencia optimista (campo version)
• Búsqueda de texto completo — mediante PostgreSQL tsvector con soporte para español
• Etiquetas — crear, asignar y desasignar etiquetas a las tarjetas
• Registro de actividad — trazabilidad de auditoría de todas las mutaciones
• Eventos en tiempo real — servidor WebSocket que transmite eventos card.created, card.updated, card.deleted, card.moved
• Reordenamiento — mover tarjetas entre listas con seguimiento de posición
• Dashboard — SPA en React + Vite con tema oscuro, login/registro, búsqueda, creación y eliminación de tarjetas
• CLI — cliente de terminal para iniciar sesión, listar, crear, mover y buscar tarjetas
• CI — flujo de GitHub Actions ejecutando pruebas en Node 20 y 22

Tecnologías

Capa	Tecnología
Backend	Express 5, TypeScript 6, Node 22
Base de datos	PostgreSQL (pool pg)
Autenticación	JWT (access + refresh tokens), bcryptjs
Tiempo real	WebSocket (ws)
Frontend	React 19, Vite 8, TypeScript 6
CLI	TypeScript, API fetch
Pruebas	Vitest 4, Supertest
CI/CD	GitHub Actions

Primeros pasos

# Instalar dependencias
npm install

# Configurar entorno
cp .env.example .env
# Completar DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

# Sembrar la base de datos con datos de prueba
npm run db:seed

# Iniciar servidor de desarrollo
npm run dev

# Ejecutar pruebas
npm run test:run

# Iniciar dashboard (terminal separada)
cd dashboard && npm install && npm run dev

Credenciales de Prueba

Tras sembrar la base de datos, puedes iniciar sesión en el dashboard usando:

• Correo: demo@taskforge.com
• Contraseña: password123

---

Project Structure

taskforge/
├── cli/                  # CLI client
│   └── index.ts
├── dashboard/            # React + Vite frontend
│   ├── src/
│   │   ├── App.tsx
│   │   ├── api.ts
│   │   └── main.tsx
│   └── package.json
├── src/                  # Backend API
│   ├── app.ts
│   ├── server.ts
│   ├── config.ts
│   ├── websocket.ts
│   ├── db/
│   │   └── pool.ts
│   ├── errors/
│   │   └── AppError.ts
│   ├── middleware/
│   │   ├── auth.ts
│   │   ├── errorHandler.ts
│   │   └── notFound.ts
│   ├── repositories/
│   │   ├── userRepository.ts
│   │   ├── cardRepository.ts
│   │   ├── labelRepository.ts
│   │   └── activityLogRepository.ts
│   ├── routes/
│   │   ├── auth.ts
│   │   ├── card.ts
│   │   ├── health.ts
│   │   ├── label.ts
│   │   └── ping.ts
│   ├── services/
│   │   ├── auth.ts
│   │   ├── card.ts
│   │   ├── label.ts
│   │   └── ping.ts
│   └── types/
│       └── api.ts
├── tests/                # Integration tests
│   ├── auth.test.ts
│   ├── card.test.ts
│   └── health.test.ts
├── .github/workflows/
│   └── test.yml
├── package.json
└── tsconfig.json

License

MIT — see LICENSE for details.