KanBAM - Agile Project Management System

Prerequisites

• node.js (v18+)
• postgresql database
• npm or yarn

Installation & setup

1. Clone the repository

   git clone <repo-url>
   cd KanBAM

2. Backend Setup

   cd backend
   npm install
   # Create a .env file and define DATABASE_URL and JWT_SECRET
   npx prisma migrate dev
   npm run dev

3. Frontend Setup

   cd ../frontend
   npm install
   npm run dev

Development

To run all tests (from repo root):

npm run test

Backend test commands:

cd backend
npm test            # same as npm run test:all
npm run test:all    # runs every backend test file in sequence
npm run test:watch  # watch mode (vitest)
npx vitest run      # run all backend tests once

Other Relevant Commands

npx prisma studio  # open database admin interface
npx prisma generate # regenerate prisma client after schema changes
npx prisma migrate dev # apply new migrations to database
npx prisma migrate reset # reset database and apply all migrations (destructive), will need to do after running tests since they modify the database

Backend API Documentation

Base URL: http://localhost:3000

All backend routes are mounted under /api.

Authentication notes:

• Public auth routes: login, register, refresh
• All other routes require the access_token http-only cookie
• Refresh flow uses the refresh_token http-only cookie
• When calling from frontend, send cookies with credentials: 'include'

User routes (/api/user)

• POST /login - login user and set auth cookies
• POST /register - register a new user
• POST /refresh - rotate access and refresh tokens
• POST /logout - clear auth cookies (auth required)
• GET /me - get current user profile (auth required)
• GET /all - list all users, global admin only (auth required)
• PATCH /avatar - update current user avatar (auth required)
• DELETE /:id - delete user by id, global admin only (auth required)

Project routes (/api/projects)

• POST /create - create project
• GET /my-projects - get projects visible to current user
• POST /add-member - add user membership to project
• POST /edit-name - update project name
• POST /edit-description - update project description
• POST /archive - archive project
• POST /unarchive - unarchive project
• POST /change-role - change member role in project
• GET /:id - get project details by id
• DELETE /:project_id/members/:user_id - remove member from project
• DELETE /:id - delete project by id

Board routes (/api/boards)

• POST /create - create board and default columns
• GET /project/:project_id - list boards in a project
• GET /:id - get full board data
• PATCH /:id/rename - rename board
• DELETE /:id - delete board

Column routes (/api/columns)

• POST /create - create board column
• PATCH /:id/rename - rename column
• PATCH /:id/reorder - reorder column position
• PATCH /:id/wip - update column wip limit
• DELETE /:id - delete column

Story routes (/api/stories)

• POST /create - create story
• GET /board/:board_id - list stories on board
• GET /:id/assignees - list assignable users for story
• GET /:id - get story with details
• PATCH /:id/finish - mark story finished
• PATCH /:id - update story fields
• DELETE /:id - delete story

Task routes (/api/tasks)

• POST /create - create task/bug under a story
• GET /:id/assignees - list assignable users for task
• GET /:id - get task with details
• PATCH /:id/move - move task to another column
• PATCH /:id/finish - mark task finished
• PATCH /:id - update task fields
• DELETE /:id - delete task

Comment routes (/api/comments)

• GET /task/:taskId - list comments for a task
• GET /story/:storyId - list comments for a story
• POST /create - create comment (task or story target)
• PATCH /:id - edit own comment
• DELETE /:id - delete own comment

Notification routes (/api/notifications)

• GET / - list current user notifications
• PATCH /:id/read - mark one notification as read
• PATCH /mark-all-read - mark all notifications as read