pal-e-docs

Phase: Board Data Model

phase-pal-e-docs-board-data-model Phase

Project

Phase: Board Data Model

Goal: Replace sprints with boards. One permanent kanban board per project. Drop sprint tables entirely.
Owner: Dev agent
Repo: forgejo_admin/pal-e-docs (DB + API), forgejo_admin/pal-e-docs-mcp (MCP tools)
Depends on: Phase 0 (Project Taxonomy Cleanup) — clean project list is prerequisite

Scope

Data Model

boards table:
Column Type Notes
id int PK auto
slug varchar(200) unique Convention: <code>board-{project-slug}</code>
name varchar(200) Display name
project_id FK → projects.id, unique One board per project. NOT NULL.
created_at datetime server_default=now()
updated_at datetime server_default=now(), onupdate=now()
board_items table:
Column Type Notes
id int PK auto
board_id FK → boards.id, CASCADE NOT NULL
item_type varchar(20) Denormalized from note_type or "issue". Values: plan, phase, issue, repo, project, todo
column varchar(20) 7 values: backlog, todo, next_up, in_progress, qa, needs_approval, done
position int Order within column. Default 0.
note_slug varchar(500) nullable Points to a pal-e-docs note
forgejo_issue_url varchar(500) nullable Points to a Forgejo issue
title varchar(500) nullable Display name (derived from note/issue title)
points int nullable Velocity tracking
labels text nullable Comma-separated labels
created_at datetime server_default=now()
updated_at datetime server_default=now(), onupdate=now()

API Endpoints

Method Path Description
GET /boards List all boards (unified view across projects)
POST /boards Create board (requires project slug)
GET /boards/{slug} Get board with item counts
PATCH /boards/{slug} Update board name
DELETE /boards/{slug} Delete board (reject if items exist)
GET /boards/{slug}/items List items (filter by column, item_type)
POST /boards/{slug}/items Add item to board
PATCH /boards/{slug}/items/{id} Update item (move column, change points)
DELETE /boards/{slug}/items/{id} Remove item from board
PATCH /boards/{slug}/items/bulk Bulk move items between columns
GET /boards/backlog/items Cross-board backlog view

Migration

  • Create boards + board_items tables
  • Drop sprints + sprint_items tables (no data migration — Sprint 3 data discarded)
  • Remove sprint enums (SprintStatus, SprintItemType, SprintColumn)

Decisions

Decision Rationale
Keep item_type (denormalized) Enables filtering ("show me just phases") without joining to notes table. Set at add-time from note's note_type or "issue" for Forgejo issues.
Keep all 7 columns qa and needs_approval are critical workflow statuses for the PR review-fix loop.
Keep labels field Used for DORA instrumentation (status:approved, etc.)
Hard cut from sprints No migration of Sprint 3 data. Drop tables. Clean start.
Board slug convention: board-{project-slug} Predictable, human-readable. Auto-generated on board creation.
project_id UNIQUE on boards Enforces one board per project at the DB level.

Sub-phases

  • 1a: DB + API — Tables, Alembic migration (drop sprints, create boards), all API endpoints, tests. Repo: pal-e-docs.
  • 1b: MCP tools — Replace 25 sprint MCP tools with board equivalents. Repo: pal-e-docs-mcp.
  • 1c: SDK — Update pal-e-docs-sdk with board operations. Repo: pal-e-docs-sdk.
  • plan-pal-e-docs — parent plan
  • plan-2026-03-01-pal-e-sprints — predecessor (completed, sprint tables being replaced)
  • phase-pal-e-docs-sprint-board-component — Phase 3, the SvelteKit UI that renders these boards
  • feedback_one_plan_per_project — one plan per project, one board per project