Task API

Enterprise-grade GraphQL Task Management System

🎯 Descripción del Proyecto

Task API es una solución backend moderna, escalable y robusta para la gestión de tareas y proyectos. Implementada con Spring Boot 4.0.5 y GraphQL, proporciona una API tipo-segura y eficiente para operaciones de CRUD sobre tareas y categorías, con soporte completo para paginación, filtrado y soft-deletes.

Diseñada siguiendo principios de arquitectura limpia (Clean Architecture) y diseño dirigido por el dominio (DDD)

---

✨ Características Principales

✅ GraphQL API moderna - Queries y Mutations fuertemente tipadas
✅ MongoDB - Persistencia NoSQL con transacciones de réplica
✅ Paginación avanzada - Soporte para offset/limit con metadatos de navegación
✅ Soft-deletes - Eliminación lógica de tareas y categorías
✅ Arquitectura limpia - Separación clara entre capas (Controller → Service → Repository → Infrastructure)
✅ Docker ready - Docker Compose con MongoDB y aplicación pre-configurados
✅ Manejo de errores robusto - Excepciones personalizadas con transformación a respuestas GraphQL
✅ CORS habilitado - Soporte para orígenes cruzados
✅ Java 25 - Aprovecha las características más recientes de la plataforma

---

🚀 Inicio Rápido

Prerrequisitos

• Java 25 o superior
• Maven 3.8+
• Docker & Docker Compose (opcional, pero recomendado)
• MongoDB 6.0+ (si no usas Docker)

Opción 1: Docker Compose (Recomendado)

docker-compose up -d

Esto iniciará:

• MongoDB con réplica configurada (puerto 27017)
• Task API en el puerto 8080
• GraphQL disponible en http://localhost:8080/graphql

Opción 2: Ejecución Local

1. Inicia MongoDB localmente

docker-compose up -d mongodb mongo-init-replica

2. Compila el proyecto

./mvnw clean package

3. Ejecuta la aplicación

./mvnw spring-boot:run

La API estará disponible en http://localhost:8080/graphql

---

📊 Arquitectura

Estructura de Capas

GraphQL Request
    ↓
[Controller] - GraphQL entry points (@QueryMapping, @MutationMapping)
    ↓
[Service] - Business Logic & Pagination
    ↓
[Repository Interface] - Domain contracts
    ↓
[Repository Adapter] - MongoDB implementation
    ↓
[MongoDB] - Persistent Data Store

Directorios Clave

Directorio	Propósito
controller/	Endpoints GraphQL (Queries y Mutations)
application/service/	Lógica de negocio e interfaces de servicios
application/dto/	Data Transfer Objects para API contracts
application/mapper/	Conversión DTO ↔ Domain Models
domain/model/	Modelos core (Task, Category)
domain/repository/	Interfaces de repositorios (contratos)
domain/exception/	Excepciones personalizadas (NotFoundException, etc.)
infrastructure/repository/	Implementaciones de repositorios (MongoDB adapters)
infrastructure/model/	MongoDB document models (@Document)
application/config/	Configuración (CORS, MongoDB, GraphQL)

---

📡 API GraphQL

Endpoint

• URL: http://localhost:8080/graphql
• UI interactiva: http://localhost:8080/graphiql (GraphQL Playground)

Queries (Lecturas)

1. Listar todas las tareas (paginadas)

query {
  findAllTasks(offset: 0, limit: 10, categoryIds: ["ID_CATEGORIA"]) {
    items {
      id
      title
      description
      completed
      categoryId
      category { id name }
      createdAt
      updatedAt
    }
    pageInfo {
      offset
      limit
      totalCount
      hasNextPage
      hasPreviousPage
    }
  }
}

2. Obtener tarea por ID

query {
  taskById(id: "TASK_ID") {
    id
    title
    description
    completed
    category { id name }
  }
}

3. Listar categorías (paginadas)

query {
  categories(offset: 0, limit: 10) {
    items {
      id
      name
      isActive
      createdAt
      updatedAt
    }
    pageInfo {
      offset
      limit
      totalCount
      hasNextPage
      hasPreviousPage
    }
  }
}

4. Obtener categoría por ID

query {
  categoryById(id: "CATEGORY_ID") {
    id
    name
    isActive
  }
}

Mutations (Escrituras)

1. Crear tarea

mutation CreateTask($input: TaskInput!) {
  createTask(input: $input) {
    id
    title
    description
    completed
    categoryId
  }
}

Variables:

{
  "input": {
    "title": "Implementar autenticación",
    "description": "Agregar JWT a la API",
    "completed": false,
    "categoryId": null
  }
}

2. Actualizar tarea

mutation UpdateTask($id: ID!, $input: TaskUpdateInput!) {
  updateTask(id: $id, input: $input) {
    id
    title
    description
    completed
  }
}

3. Alternar estado de tarea

mutation {
  toggleTask(id: "TASK_ID") {
    id
    completed
  }
}

4. Eliminar tarea (soft-delete)

mutation {
  toggleDeleteTask(id: "TASK_ID") {
    id
    deleted
  }
}

5. Crear categoría

mutation CreateCategory($input: CategoryInput!) {
  createCategory(input: $input) {
    id
    name
    isActive
  }
}

Variables:

{
  "input": {
    "name": "Trabajo"
  }
}

6. Actualizar categoría

mutation UpdateCategory($id: ID!, $input: CategoryUpdateInput!) {
  updateCategory(id: $id, input: $input) {
    id
    name
    isActive
  }
}

7. Eliminar categoría (soft-delete)

mutation {
  toggleDeleteCategory(id: "CATEGORY_ID") {
    id
    deleted
  }
}

---

🧪 Testing

Ejecutar todos los tests

./mvnw test

Ejecutar un test específico

./mvnw test -Dtest=TaskApiApplicationTests
./mvnw test -Dtest=TaskApiApplicationTests#testMethodName

---

🔧 Configuración

Variables de Entorno

Variable	Descripción	Default
SPRING_DATA_MONGODB_URI	URI de conexión MongoDB	mongodb://localhost:27017/task_db
SERVER_PORT	Puerto del servidor	8080
SPRING_PROFILES_ACTIVE	Perfil activo (dev, prod)	-
JAVA_OPTS	Opciones JVM adicionales	-

Configuración en application.properties

spring.data.mongodb.uri=${SPRING_DATA_MONGODB_URI:mongodb://localhost:27017/task_db}
server.port=8080

---

🐳 Docker

Build de imagen personalizada

docker build -t task-api:latest .

Ejecutar con Docker Compose

docker-compose up --build

La aplicación estará disponible en: http://localhost:8080/graphql

---

📋 Patrones & Convenciones

Repository Pattern

• Interfaces en: domain/repository/ (contratos)
• Implementaciones en: infrastructure/repository/ (adapters)
• Los servicios manejan paginación, validación y lógica de negocio
• Los repositorios retornan modelos de dominio (no documentos MongoDB)

Manejo de Errores

• Excepciones personalizadas: NotFoundException, ValidationException
• Transformadas automáticamente por GraphQlExceptionHandler
• Respuestas en formato GraphQL estándar

Soft-Deletes

• Modelos incluyen campo deleted: Boolean
• Queries filtran automáticamente registros eliminados (a menos que se especifique)
• toggleDelete* cambia el estado: deleted = !deleted

Validación

• Anotaciones @Valid en inputs GraphQL
• Validaciones adicionales en capa de servicios

---

📦 Stack Tecnológico

Componente	Versión
Java	25
Spring Boot	4.0.5
Spring GraphQL	Latest
Spring Data MongoDB	Latest
MongoDB	6.0+
Maven	3.8+
Docker	Latest

---

🚨 Troubleshooting

MongoDB no se conecta

# Verifica que MongoDB esté corriendo
docker-compose logs mongodb

# Reinicia los servicios
docker-compose down && docker-compose up -d

Puerto 8080 en uso

# Cambia el puerto en docker-compose.yml
ports:
  - "8081:8080"

# O establece variable de entorno
export SERVER_PORT=8081

Tests fallan

# Limpia el proyecto
./mvnw clean

# Ejecuta tests con output detallado
./mvnw test -X

---

📈 Performance & Escalabilidad

• Paginación optimizada - Soporte para grandes volúmenes de datos
• Índices MongoDB - Configurables para queries comunes
• Lazy loading - Categorías se cargan bajo demanda
• Connection pooling - Configurado por defecto en Spring Data MongoDB

---

Última actualización: Abril 2026
Versión: 0.0.1-SNAPSHOT