david/kanban-app
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kanban-app/docs/kanban_implementation_summary.md

9.1 KiB
Raw Blame History

Kanban Backend Implementation Summary

Overview

This document summarizes the Kanban backend implementation for the project. The backend provides a complete API for managing Kanban boards, lists, cards, labels, checklists, and comments.

Database Schema

Tables Created

  1. boards - Main board entities

    • id, name, description, closed, url, short_link, short_url
    • user_id (foreign key to users)
    • date_last_activity, date_last_view, created_at, updated_at
    • JSONB fields: prefs, label_names, limits
    • Relationships: lists, cards, labels

  2. lists - Board columns/lists

    • id, name, closed, pos
    • board_id (foreign key to boards)
    • created_at, updated_at
    • Relationships: cards

  3. cards - Task cards within lists

    • id, name, description, closed, due, due_complete, pos, id_short
    • board_id (foreign key to boards), list_id (foreign key to lists)
    • date_last_activity, created_at, updated_at
    • JSONB fields: badges, cover, desc_data
    • Relationships: checklists, labels, comments

  4. labels - Color-coded tags

    • id, name, color, uses
    • board_id (foreign key to boards)
    • created_at, updated_at
    • Relationships: card_labels

  5. card_labels - Many-to-many relationship between cards and labels

    • id, card_id, label_id
    • Unique constraint on (card_id, label_id)

  6. checklists - Checklists within cards

    • id, name, pos
    • board_id (foreign key to boards), card_id (foreign key to cards)
    • created_at, updated_at
    • Relationships: check_items

  7. check_items - Items within checklists

    • id, name, pos, state, due
    • checklist_id (foreign key to checklists), user_id (foreign key to users)
    • created_at, updated_at

  8. comments - Comments on cards

    • id, text
    • card_id (foreign key to cards), user_id (foreign key to users)
    • created_at, updated_at

API Endpoints

Boards (/api/boards)

  • GET /api/boards - Get all boards for current user
  • GET /api/boards/<id> - Get board with full details (lists, cards, labels)
  • POST /api/boards - Create new board
  • PUT /api/boards/<id> - Update board
  • DELETE /api/boards/<id> - Delete board

Lists (/api/lists, /api/boards/<id>/lists)

  • POST /api/boards/<board_id>/lists - Create list in board
  • PUT /api/lists/<id> - Update list
  • DELETE /api/lists/<id> - Delete list

Cards (/api/cards, /api/lists/<id>/cards)

  • POST /api/lists/<list_id>/cards - Create card in list
  • GET /api/cards/<id> - Get card with full details
  • PUT /api/cards/<id> - Update card (includes moving between lists)
  • DELETE /api/cards/<id> - Delete card

Labels (/api/boards/<id>/labels, /api/cards/<id>/labels)

  • GET /api/boards/<board_id>/labels - Get all labels for board
  • POST /api/boards/<board_id>/labels - Create label
  • POST /api/cards/<card_id>/labels - Add label to card
  • DELETE /api/cards/<card_id>/labels/<label_id> - Remove label from card

Checklists (/api/checklists, /api/cards/<id>/checklists)

  • POST /api/cards/<card_id>/checklists - Create checklist
  • DELETE /api/checklists/<id> - Delete checklist

Check Items (/api/check-items, /api/checklists/<id>/items)

  • POST /api/checklists/<checklist_id>/items - Create check item
  • PUT /api/check-items/<id> - Update check item
  • DELETE /api/check-items/<id> - Delete check item

Comments (/api/comments, /api/cards/<id>/comments)

  • GET /api/cards/<card_id>/comments - Get all comments for card
  • POST /api/cards/<card_id>/comments - Create comment
  • PUT /api/comments/<id> - Update comment
  • DELETE /api/comments/<id> - Delete comment

Key Features

Authentication

  • All endpoints (except register/login) require JWT authentication
  • User can only access their own boards and related resources
  • Comments can only be edited/deleted by their author

Data Integrity

  • Cascading deletes ensure cleanup of related data
  • Foreign key constraints maintain referential integrity
  • Unique constraints prevent duplicate card-label associations

Position Tracking

  • All orderable entities (lists, cards, checklists, check items) have pos field
  • Enables flexible sorting and drag-and-drop functionality

Activity Tracking

  • Boards track date_last_activity and date_last_view
  • Cards track date_last_activity
  • Useful for showing recent activity

JSONB Fields

  • Flexible storage for complex data (prefs, limits, badges, cover, desc_data)
  • Allows extensibility without schema changes
  • Supports Trello-like feature parity

File Structure

backend/app/
├── models/
│   ├── board.py          # Board model
│   ├── list_model.py     # List model (named to avoid Python conflict)
│   ├── card.py           # Card model
│   ├── label.py          # Label model
│   ├── card_label.py     # Card-Label junction table
│   ├── checklist.py      # Checklist model
│   ├── check_item.py     # CheckItem model
│   ├── comment.py        # Comment model
│   └── user.py          # Updated with boards relationship
├── routes/
│   └── kanban.py        # All Kanban API routes
└── __init__.py          # Updated to import models and register blueprint

docs/
├── kanban_api.md        # Complete API documentation
└── kanban_implementation_summary.md  # This file

Migration

Migration file: backend/migrations/versions/1c0b9dfbd933_add_kanban_models_board_list_card_label_.py

To apply migrations:

cd backend && . venv/bin/activate && flask db upgrade

Usage Flow

Typical User Workflow

  1. Register/Login

    • User registers account or logs in
    • Receives JWT token for authentication

  2. Create Board

    • User creates a new board
    • Board is associated with their user ID

  3. Add Lists

    • User adds lists (columns) to the board
    • Examples: "To Do", "In Progress", "Done"

  4. Add Cards

    • User creates cards within lists
    • Cards can have descriptions, due dates, etc.

  5. Enhance Cards

    • Add labels for categorization
    • Add checklists for subtasks
    • Add comments for collaboration

  6. Manage Work

    • Move cards between lists (drag-and-drop)
    • Update card details
    • Mark checklist items as complete
    • Delete completed items

Design Decisions

Single User App

  • No organization or membership models (as specified)
  • Each board belongs to exactly one user
  • Simplifies permissions model

Trello-Inspired Schema

  • Uses similar field names and structure as Trello
  • Makes it familiar to users
  • Supports importing from Trello JSON exports

Position-Based Ordering

  • Uses float pos field for ordering
  • Allows inserting items between others
  • Supports infinite granularity for drag-and-drop

Cascading Deletes

  • Deleting a board deletes all its lists, cards, labels, etc.
  • Deleting a list deletes all its cards
  • Ensures no orphaned data

JSONB for Flexible Data

  • Stores complex nested data without normalized tables
  • Simplifies schema for optional features
  • Maintains flexibility for future enhancements

Next Steps

Backend

  • Add validation schemas (Pydantic)
  • Add comprehensive tests
  • Add rate limiting
  • Add file upload support for attachments
  • Add activity logging/history
  • Add search functionality
  • Add filtering and sorting options

Frontend

  • Create board list view
  • Create board detail view with drag-and-drop
  • Implement card creation/editing
  • Implement label management
  • Implement checklist functionality
  • Implement comments
  • Add real-time updates (WebSocket)

Testing

Test the API using the examples in docs/kanban_api.md or use tools like:

  • Postman
  • Insomnia
  • curl (command line)

Example:

# Start the backend server
make dev-services  # Start postgres & redis
make dev-backend    # Start Flask server

# Test endpoints
curl http://localhost:5000/api/health

Security Considerations

  • JWT authentication required for all operations
  • User isolation: users can only access their own resources
  • SQL injection prevention through SQLAlchemy ORM
  • Input validation on all endpoints
  • CORS configured for frontend integration

Performance Notes

  • Indexed fields: user_id, board_id, list_id, card_id, etc.
  • Lazy loading relationships to avoid N+1 queries
  • Efficient queries using SQLAlchemy's query builder
  • JSONB fields use PostgreSQL's optimized JSON storage

Troubleshooting

Migration Issues

# Reset migrations (WARNING: deletes data)
cd backend && . venv/bin/activate && flask db downgrade base
rm -rf migrations/versions/*.py
flask db migrate -m "Initial migration"
flask db upgrade

Database Connection Issues

# Restart services
make dev-stop-services
make dev-services

Import Errors

# Ensure venv is activated
cd backend && . venv/bin/activate
pip install -r requirements/dev.txt

Summary

The Kanban backend is now fully implemented with:

  • ✅ Complete database schema
  • ✅ RESTful API endpoints
  • ✅ Authentication and authorization
  • ✅ Data integrity and validation
  • ✅ Comprehensive documentation
  • ✅ Database migration

The backend is ready for frontend integration and testing.