Quickstart Guide

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher

npm

Version 9 or higher

Verify your installations by running node --version and npm --version in your terminal.

Installation

Clone the Repository

First, clone the Task Manager repository to your local machine:

git clone https://github.com/JoseJavega/taskManager.git
cd taskManager

This downloads the complete application including both the API backend and web frontend.

Install Dependencies

Install all required npm packages:

npm install

This installs:

express (5.1.0) - Web framework
db-local (3.1.0) - JSON database
zod (4.1.12) - Schema validation
cors (2.8.5) - Cross-origin support
dotenv (17.2.3) - Environment configuration

Configure Environment Variables

Create a .env file in the project root directory:

touch .env

Add the following configuration:

PORT=3000

The PORT variable determines which port the Express server listens on. You can change this to any available port if 3000 is already in use.

Start the Server

Launch the application in development mode:

npm run dev

You should see:

servidor corriendo en el puerto:3000

Development mode uses Node.js watch mode (--watch flag), automatically restarting the server when source files change.

For production, use:

npm start

Verify Installation

Open your browser and navigate to:

http://localhost:3000

You should see the Task Manager web interface with “Gestor de tareas” as the header.To verify the API is responding, visit:

http://localhost:3000/api/tasks

You should receive an empty JSON array: []

Creating Your First Task

Now that Task Manager is running, let’s create a task using both the API and the web interface.

Option 1: Using the REST API

Create a Task via POST Request

Use curl or any HTTP client to create your first task:

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Task",
    "description": "Learning Task Manager",
    "completed": false
  }'

The API validates your request using the Zod schema defined in src/schemas/task.js:3:

const taskSchema = z.object({
  title: z.string().min(3).max(25),
  description: z.string().max(25).optional(),
  completed: z.boolean().optional(),
  categoryId: z.string().optional()
});

Examine the Response

The API returns a 201 Created status with the complete task object:

{
  "_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "My First Task",
  "description": "Learning Task Manager",
  "completed": false,
  "categoryId": "",
  "createdAt": "2026-03-11T10:30:00.123Z"
}

Notice:

_id is automatically generated using UUID v4 (src/models/task.js:7)
createdAt timestamp is set automatically
categoryId defaults to empty string (“uncategorized”)
completed is false as specified

Retrieve All Tasks

Verify your task was created by fetching all tasks:

curl http://localhost:3000/api/tasks

Response:

[
  {
    "_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "My First Task",
    "description": "Learning Task Manager",
    "completed": false,
    "categoryId": "",
    "createdAt": "2026-03-11T10:30:00.123Z"
  }
]

Update the Task

Mark your task as completed using PATCH:

curl -X PATCH http://localhost:3000/api/tasks/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

The response now includes automatic timestamps:

{
  "_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "My First Task",
  "description": "Learning Task Manager",
  "completed": true,
  "categoryId": "",
  "createdAt": "2026-03-11T10:30:00.123Z",
  "updatedAt": "2026-03-11T10:35:22.456Z",
  "finishedAt": "2026-03-11T10:35:22.456Z"
}

The finishedAt timestamp is automatically set when completed changes from false to true (logic in src/models/task.js:57).

Option 2: Using the Web Interface

Open the Application

Navigate to http://localhost:3000 in your browser. You’ll see the main task management interface with:

Header: “Gestor de tareas”
”+ Crear tarea” button
“Gestionar Categorías” button
Empty task list (initially)

Click Create Task

Click the green ”+ Crear tarea” button. This opens a modal dialog with a task form.The modal is managed by public/js/controllers/Modal.js and the form is rendered by public/js/views/Task.js.

Fill in Task Details

In the modal form, enter:

Title: “My First Task” (required, 3-25 characters)
Description: “Learning Task Manager” (optional, max 25 characters)
Finished: Leave unchecked (defaults to false)
Category: Select “uncategorized” (default option)

The title field enforces a minimum of 3 characters and maximum of 25 characters. The form will display validation errors if these constraints aren’t met.

Save the Task

Click the “Guardar” (Save) button. The form data is sent to the API using the TaskService class (public/js/services/Task.js:26):

async save(data) {
  const taskCompleted = data.finished === "on" ? true : false;
  const categoryId = data.categoryId === "uncategorized" ? "" : data.categoryId;
  
  const result = await fetch(`${this.apiClient}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      title: data.title,
      description: data.description,
      completed: taskCompleted,
      categoryId: categoryId
    })
  });
  
  return await result.json();
}

The modal closes and your new task appears in the task list.

Interact with Your Task

Your task now appears in the interface. You can:

View details - Click on the task to see full information
Mark complete - Check the completion checkbox to update status
Edit - Click the edit icon to modify title or description
Delete - Click the delete icon to remove the task

All interactions trigger API calls through the TaskService class and update the UI in real-time.

Working with Categories

Organize your tasks using categories:

Create a Category

Using the API:

curl -X POST http://localhost:3000/api/taskCategories \
  -H "Content-Type: application/json" \
  -d '{"name": "Work"}'

Response:

{
  "_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Work"
}

Assign Task to Category

Create a task with a category:

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare meeting",
    "description": "Q1 Review slides",
    "categoryId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  }'

Filter Tasks by Category

Retrieve all tasks in a specific category:

curl "http://localhost:3000/api/tasks?categoryId=b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"

The model’s getAll method (src/models/task.js:100) supports category filtering:

static async getAll(filters = {}) {
  const query = {};
  if (filters.categoryId) {
    query.categoryId = filters.categoryId;
  }
  return await Tasks.find(filters);
}

Common API Operations

Here’s a quick reference for essential API operations:

Get All Tasks

GET /api/tasks

Get Single Task

GET /api/tasks/:id

Create Task

POST /api/tasks
Body: {title, description?, completed?, categoryId?}

Update Task

PATCH /api/tasks/:id
Body: {any task fields to update}

Delete Task

DELETE /api/tasks/:id

List Categories

GET /api/taskCategories

Validation and Error Handling

Task Manager uses Zod for runtime validation. Understanding validation helps you handle errors gracefully:

Common Validation Errors

Title Too Short

Error: Title must be at least 3 characters

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Hi"}'

Response: 400 Bad Request with Zod error details

Title Too Long

Error: Title cannot exceed 25 characters

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "This is a very long title that exceeds the limit"}'

Response: 400 Bad Request

Task Not Found

Error: Attempting to update or delete a non-existent task

curl -X DELETE http://localhost:3000/api/tasks/invalid-uuid

Response: 404 Not Found with message “Task not found”This check happens in the controller (src/controllers/task.js:14):

const task = await TaskModel.getById(id);
if (!task) {
  res.status(404).json({ message: "Task not found" });
}

Next Steps

Now that you have Task Manager running:

Explore the API

Learn about all available endpoints, request formats, and response codes

Architecture Deep Dive

Understand the modular design and how components interact

Task Management Features

Learn about task CRUD operations and completion tracking

Category Management

Organize your tasks with custom categories

Troubleshooting

Port Already in Use

If port 3000 is already in use:

Change the PORT in your .env file
Restart the server
Update the API base URL in public/js/config.js if accessing the frontend

Database Not Persisting

Ensure the ./src/DB/ directory exists and is writable. The db-local library creates JSON files here:

ls -la src/DB/
# Should show tasks.json and taskCategories.json after first use

CORS Errors in Browser

The application includes CORS middleware (src/middlewares/cors.js). If you’re accessing from a different origin, you may need to configure allowed origins.

Module Not Found Errors

Ensure all dependencies are installed:

rm -rf node_modules package-lock.json
npm install

For additional help, check the project’s GitHub repository or review the detailed API documentation in src/API.md.

Get Started

Core Features

Architecture

Prerequisites

Node.js

npm

Installation

Creating Your First Task

Option 1: Using the REST API

Option 2: Using the Web Interface

Working with Categories

Common API Operations

Get All Tasks

Get Single Task

Create Task

Update Task

Delete Task

List Categories

Validation and Error Handling

Common Validation Errors

Next Steps

Explore the API

Architecture Deep Dive

Task Management Features

Category Management

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

​Prerequisites

Node.js

npm

​Installation

​Creating Your First Task

​Option 1: Using the REST API

​Option 2: Using the Web Interface

​Working with Categories

​Common API Operations

Get All Tasks

Get Single Task

Create Task

Update Task

Delete Task

List Categories

​Validation and Error Handling

​Common Validation Errors

​Next Steps

Explore the API

Architecture Deep Dive

Task Management Features

Category Management

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Installation

Creating Your First Task

Option 1: Using the REST API

Option 2: Using the Web Interface

Working with Categories

Common API Operations

Validation and Error Handling

Common Validation Errors

Next Steps

Troubleshooting