TaskFlow

TaskFlow is a task-management REST API. People can sign up, sign in with JWT-protected sessions, create projects, add tasks inside those projects, assign work to teammates, filter task lists (by status or assignee), and inspect per-project statistics (counts by status and by assignee).

The service is written in Go with the Gin router, persists data in PostgreSQL (SQL via pgx), and uses golang-migrate for schema changes. HTTP handlers stay thin; validation and authorization live in a service layer; database access goes through repository interfaces so the core logic can be tested without a live database.

Requirements

• Docker and Docker Compose
• GNU Make (optional but used below)

To work on the Go code only, install a Go toolchain matching backend/go.mod and a reachable Postgres instance.

Quick start

cp .env.example .env
make setup

API: http://localhost:8080 · Health: GET /healthz

Stop and remove containers and volumes:

make down

Configuration

Copy .env.example to .env. Values are read by Docker Compose and the API container.

Variable	Purpose
DB_HOST	Postgres host (use postgres with Compose)
DB_PORT	Postgres port
DB_USER, DB_PASSWORD, DB_NAME	Database credentials
DB_SSLMODE	e.g. disable locally
SERVER_PORT	HTTP port inside the API container (mapped to 8080 in Compose)
JWT_SECRET	Required; use a long random value in production
JWT_EXPIRY	e.g. 24h

Required env vars are validated at startup; missing values fail fast.

Project layout

├── Makefile                 # common workflows
├── docker-compose.yml       # postgres + api
├── .env.example
└── backend/
    ├── cmd/server/          # entrypoint: config, migrations, HTTP server
    ├── internal/
    │   ├── handler/         # Gin routes, JSON, auth middleware
    │   ├── service/         # validation, authorization
    │   ├── repository/      # interfaces + Postgres (pgx)
    │   ├── models/          # request/domain structs
    │   ├── apperrors/       # typed errors → HTTP in handler
    │   ├── config/          # env loading
    │   ├── constants/       # shared literals
    │   └── utils/           # small helpers
    ├── migrations/          # golang-migrate SQL
    ├── scripts/seed.sql     # optional seed (used by `make seed`)
    └── tests/integration/   # HTTP + DB tests

The docs/ directory is gitignored so you can keep personal notes, specs, or task checklists next to the code without committing them.

Migrations run when the API process starts (before serving traffic).

Makefile targets

Target	Description
make setup	docker compose up, wait for health, run seed
make up / make down	Start stack / tear down including volumes
make seed	Apply scripts/seed.sql to the Compose database
make build	Build server binary to backend/bin/taskflow
make test-unit	Go unit tests under internal/
make test-integration	Integration tests (starts a throwaway Postgres on 5433)
make test	Unit + integration
make fmt / make tidy	Format / tidy modules in backend/

Tests

make test-unit          # fast, no DB
make test-integration   # needs Docker (postgres:16 on host port 5433)
make test

API overview

A configured Postman Collection (Taskflow_Postman_Collection.json) is available in the root directory. You can import this directly into Postman to easily test all endpoints. The collection features automatic setup of variables like Bearer tokens, project IDs, task IDs, and user IDs during creating/login workflows.

Base URL: http://localhost:8080 · JSON everywhere.

Protected routes: Authorization: Bearer <token>.

Area	Examples
Auth	POST /auth/register, POST /auth/login
Projects	GET/POST /projects, GET/PATCH/DELETE /projects/:id
Tasks	GET/POST /projects/:id/tasks, PATCH/DELETE /tasks/:id, GET /projects/:id/stats

Query helpers: GET /projects?page=&limit=, GET /projects/:id/tasks?status=&assignee=&page=&limit=.

Validation errors return 400 with {"error":"validation failed","fields":{...}}. Other errors use {"error":"<message>"} with the appropriate status (401, 403, 404, 409, 500).

Seed user (after make seed)

[email protected] / password123