# PlatphormNews Kanban (Full Documentation)

The official Kanban board for the PlatphormNews Kanban network — AI-ready, MCP-integrated project management.

## Capabilities & Projects
We support the following isolated project boards:
- **Main Board** (`default`): Default kanban board
- **Engineering** (`engineering`): Engineering team board
- **Marketing** (`marketing`): Marketing team board
- **Design** (`design`): Design team board

- **Task Management:** Create, read, update, delete tasks via REST API or MCP tool calls.
- **Automation Rules:** Event-driven task movement based on due dates, subtasks, and custom fields.
- **Calendar Sync:** Bi-directional sync with `calendar.platphormnews.com`.
- **Activity Log:** Audit trail of all board changes, exposed as RSS and JSON.
- **MCP Integration:** Full AI agent integration — manifest, tool listing, tool invocation at `/api/mcp`.
- **Webhooks:** Receives signed events from the PlatphormNews network hub.

## MCP Tools (via POST /api/mcp with action:"tool_call")
- `get_board(projectId?)` — Retrieve full board state
- `list_tasks(projectId?, columnId?)` — List tasks
- `create_task(projectId?, title, ...)` — Create a task
- `update_task(id, ...)` — Patch task fields
- `delete_task(id)` — Permanently remove a task
- `get_activities(projectId?, limit?)` — Fetch recent activity
- `get_health()` — Check service health
- `list_projects(includeCalendar?)` — List available project boards
- `sync_project_calendar(projectId)` — Sync tasks with due dates to the calendar

## API Documentation
- OpenAPI 3.1.0: https://kanban.platphormnews.com/api/v1/openapi.json
- Human docs: https://kanban.platphormnews.com/api/docs
- MCP manifest: https://kanban.platphormnews.com/api/mcp

## Discovery
- Sitemap: https://kanban.platphormnews.com/sitemap.xml
- llms.txt: https://kanban.platphormnews.com/llms.txt
- llms-index: https://kanban.platphormnews.com/llms-index.json
- Network manifest: https://kanban.platphormnews.com/network.manifest
- AI plugin: https://kanban.platphormnews.com/.well-known/ai-plugin.json
- Links: https://kanban.platphormnews.com/.well-known/links.json

---

## README.md Content
# PlatphormNews Kanban 📋

Beep Boop 

The central project management hub for the PlatphormNews network — built with Next.js 15, TypeScript, Tailwind CSS, and Vitest.

[![CI](https://github.com/mbarbine/kanban-board-webby/actions/workflows/ci.yml/badge.svg)](https://github.com/mbarbine/kanban-board-webby/actions/workflows/ci.yml)

## Features

| Feature | Description |
| :--- | :--- |
| **📋 Kanban Board** | Drag-and-drop columns and tasks with real-time persistence. |
| **⚡ Automation Rules** | Trigger-based rules that automatically move tasks (overdue, all-subtasks-done, custom-field match). |
| **📅 Calendar Sync** | Two-way synchronisation with `calendar.platphormnews.com`. |
| **🌐 Network Integration** | Receives signed webhook events from Jobs, Fortune, Fashion, and the MCP hub. |
| **🤖 MCP Ready** | Model Context Protocol manifest at `/api/mcp` for AI agents. |
| **📡 RSS Feed** | Real-time activity stream at `/feed.xml`. |
| **🔐 Secure Webhooks** | HMAC-SHA256-signed events via `X-Webhook-Signature`. |
| **🎨 ASCII Export** | Export the board as ASCII art (proxied to `ascii.platphormnews.com`). |
| **🕵️ PH3AR Admin Mode** | Secret modal for network-wide admin access. |
| **🌙 Dark Mode** | Full light/dark theme with a one-click toggle. |
| **📊 Board State Sync** | Server-side board state shared across tabs via `GET/PUT /api/v1/board` with ETag polling every 10 s. |

## Getting Started

### 1. Clone the repository

```bash
git clone https://github.com/mbarbine/kanban-board-webby.git
cd kanban-board-webby
```

### 2. Install dependencies

```bash
npm install
```

### 3. Configure environment variables

Create a `.env.local` file in the project root:

```env
# Secret for signing board state (optional)
BOARD_STATE_SECRET="your-secret-key"

# Secret for verifying incoming webhooks
PLATPHORMNEWS_WEBHOOK_SECRET="your-webhook-secret"

# API Authentication (Bearer Token)
API_SECRET="your-api-secret"
```

### 4. Start the development server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

## Architecture

```
app/                    Next.js 15 app router
  api/v1/
    board/              GET/PUT board state (server-side sync)
    calendar/           Proxy to calendar.platphormnews.com
    ascii/              Proxy to ascii.platphormnews.com
    openapi.json/       OpenAPI 3.1.0 spec
    health/             Health-check endpoint
    mcp/                Model Context Protocol manifest
  webhooks/
    platphormnews/      Inbound HMAC-signed events

components/
  kanban-board.tsx      Top-level board with hydration + server sync
  column.tsx            Droppable column with task list
  task-card.tsx         Draggable task card
  task-detail-sidebar.tsx  Slide-in task editor (subtasks, custom fields)
  automation-rules.tsx  Create / toggle / delete automation rules
  calendar-integration.tsx  Calendar connection and event import

lib/
  automation.ts         Pure automation-rule logic (checkCondition, applyRules)
  storage.ts            localStorage helpers + server sync (fetchFromServer, syncToServer)
  board-store.ts        In-memory server-side board store with ETag
  constants.ts          Network URLs, site metadata
  utils.ts              cn(), generateId(), formatDate()
  json-ld.ts            Structured-data helpers (JSON-LD)

types/
  kanban.ts             Task, Column, Rule, Subtask, CustomField, Activity

__tests__/
  api/                  Unit tests for API routes
  lib/                  Unit tests for lib modules (storage, automation, utils, …)
  integration/          Integration tests (board API round-trips, storage ↔ server)
```

## Automation Rules

Rules are configured in the **🤖 Automation** tab. Each rule has:

- **Condition** — `due-date: is-overdue` | `subtasks-completed: all-completed` | `custom-field: equals / contains`
- **Action** — `move-to-column` (target column ID)

## Integrations

- **MCP Hubs:** `mcp.platphormnews.com` and `claws.platphormnews.com`
- **Network Graph:** Registered with `platphormnews.com/api/network/graph` and `/api/docs`
- **SEO / AEO:** Structured data added including `FAQPage` JSON-LD.

The pure evaluation logic lives in `lib/automation.ts` and is fully unit-tested in `__tests__/lib/automation.test.ts`.

## API Reference

| Method | Path | Description |
| :--- | :--- | :--- |
| `GET` | `/api/v1/board` | Fetch current board state (columns + rules + ETag). Returns `204` when no state has been saved yet. |
| `PUT` | `/api/v1/board` | Save board state. Body: `{ columns, rules }`. Returns the updated state + new ETag. |
| `POST` | `/api/v1/calendar` | Push a task as a calendar event. |
| `GET` | `/api/v1/calendar` | Fetch upcoming calendar events. |
| `POST` | `/api/v1/ascii` | Export board as ASCII art. Body: `{ columns }`. |
| `GET` | `/api/v1/health` | Health-check (uptime, version). |
| `GET` | `/api/health` | Direct health-check endpoint for legacy compatibility. |
| `GET` | `/api/mcp` | MCP capabilities manifest. |
| `GET` | `/api/v1/openapi.json` | OpenAPI 3.1.0 specification. |
| `POST` | `/api/webhooks/platphormnews` | Inbound signed events from the network. |
| `GET` | `/feed.xml` | RSS 2.0 activity feed. |

### Authentication

Protected endpoints accept a Bearer token:

```bash
curl -H "Authorization: Bearer <API_SECRET>" \
  https://kanban.platphormnews.com/api/v1/board
```

## Running Tests

```bash
# Run the full test suite (236 tests)
npm test

# Watch mode
./node_modules/.bin/vitest

# Type-check only
./node_modules/.bin/tsc --noEmit
```

## Building for Production

```bash
npm run build
npm start
```

## Admin Access (PH3AR)

Authorized personnel can open the network administration modal by:

1. Typing `PH3AR` rapidly anywhere on the page.
2. Clicking the theme toggle button 5 times in quick succession.

---

© 2026 PlatphormNews. All rights reserved.