nips/100.md

NIP-100
======

Kanban Boards
------------

`draft` `optional`

This NIP defines a protocol for creating and managing Kanban boards on Nostr.

## Abstract

This NIP introduces event kinds and conventions for implementing Kanban boards, allowing users to create boards with multiple columns and cards that can be organized and tracked in a visual workflow.

## Motivation

Kanban boards are a popular project management tool that enables visual organization of tasks and workflows. Adding native Kanban support to Nostr allows for decentralized project management while maintaining the platform's permissionless and censorship-resistant nature.

## Specification

### Board Event 

```javascript
{
    "created_at": 34324234234, //<Unix timestamp in seconds>
    "kind": 30301,
    "tags": [
        ["d", "<board-d-identifier>"],
        ["title", "Board Name"],
        ["description","Board Description"], //can contain markdown too
        ["alt","A board to track my work"], //Human-readable plaintext summary to be shown in non-supporting clients - as per NIP-31

        // List of all columns in the board below in format ["col","col-id","name","order"]
        ["col", "col1-id", "To Do", "0"],
        ["col", "col2-id", "In Progress", "1"], 
        ["col", "col3-id", "Done", "2"],

        // Clients may designate a 'maintainers' list who can add/edit cards in this board
        [ "p", "82341f882b6eabcd2ba7f1ef90aad961cf074af15b9ef44a09f9d2a8fbfbe6a2" ],  
        [ "p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52" ],  
        [ "p", "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c" ],   
    // other fields...
    ]
}
```

In case there are no `p` tags to designate maintainers, the owner of the board is the only person who can publish cards on the boards.

Editing the board event is possible only by the creator of the board. 

### Card Event

```javascript
{
    "created_at": 34324234234, //<Unix timestamp in seconds>
    "kind": 30302,
    "tags": [
        ["d", "<card-d-identifier>"],
        ["title", "Card Title"],
        ["description","Card Description"], //can contain markdown too
        ["alt","A card representing a task"], //Human-readable plaintext summary to be shown in non-supporting clients - as per NIP-31
        ["s", "To do"], //status of the card
        ["rank","10"], // order of the card in the column - cards may be displayed in the ascending order of rank by default

        // card url attachments with 'u' tags similar to NIP-98
        ["u","https://attachment1"],
        ["u","https://attachment2"],

        // add assignees using 'p' tag
        [ "p", "82341f882b6eabcd2ba7f1ef90aad961cf074af15b9ef44a09f9d2a8fbfbe6a2"],
        [ "p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],  
        [ "p", "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c"], 

        // The board this card will be a part of. 
        ["a", "30301:<board-creator-pubkey>:<board-d-identifier>", "<optional-relay-url>"],  
       
    ],
    // other fields...
}
```

When editing a card, the maintainers can copy the card event with the `d` tag intact and publish a new event. 

When a client gets multiple card events with the same `d` tag, it takes the latest one by any maintainer or the creator of the board event as the source of truth.

### Tracker Card Event

In case one wants to just track another nostr event (like a tracker card, without modifying the original event), one can designate a tracker card using a `k` tag to denote kind and `e` tag to denote the nostr event to be tracked.  

```javascript
{
    "created_at": 34324234234, //<Unix timestamp in seconds>
    "kind": 30302,
    "tags": [
        ["d", "<new-tracker-card-d-identifier>"],
        ["k", "1"], //this one tracks a text note
        ["e", "<event-id>", "<relay-url>"] // as per NIP-10 
        // other fields as per card event above...
    ],
}
```
In case of tracking a replaceable event, one can use `a` tag instead of the `e` tag above.

In case of tracking another Kanban card (30302) event, one cannot use 'a' tag as that is already used for board association.  Hence, we use tags similar to git issues (NIP-34)
```javascript
{
    "created_at": 34324234234, //<Unix timestamp in seconds>
    "kind": 30302,
    "tags": [
        ["d", "<new-tracker-card-d-identifier>"],
        ["k", "30302"], //this one tracks a text note
        ["refs/board", "30301:<target-board-creator-pubkey>:<target-board-d-identifier>"], // very much like git issues
        ["refs/card", "<tracked-card-d-identifier>"
    ],
}
```

The clients MAY display this tracker card like they display the tracked event, or using the 'alt' tag of the original event if not supported.

Any `30302` event with a `k` tag will be treated as a tracker card.

#### Automatic movement of tracker cards

In case of tracked card, its status is deemed to be the `s` tag value of the event it tracks. 

This allows the automatic movement of a card (like a Git issue) across different columns as the card's status changes in the source system, without any manual updates in the board.  

If the tracked event does not have an `s` tag, then tracker card event's `s` tag is shown as the status of the card.

### Event Kinds

- 30301: Kanban Board Definition
- 30302: Kanban Card

### Required Tags

#### Board Events (kind: 30301)
- `d`: Unique identifier for the board
- `title`: Board name

#### Card Events (kind: 30302)
- `d`: Unique identifier for the card
- `title`: Card title
- `a`: This points to the board that this card belongs to

### Access Control

1. Only the board creator can:
   - Modify board

2. Only the board maintainers can:
   - Add a card to the board
   - Publish edits to the existing cards (including the status)

2. Any user can:
   - View the board and cards
   - React, comment, zap on board and cards

### Client Behavior

Clients MAY:
- Display boards in a visual column layout
- Allow drag-and-drop card movement for authorized users
- Implement proper authorization checks before allowing modifications
- Implement additional features like card labels, due dates, or assignments
- Support board templates
- Provide filtering and search capabilities
- Prioritize to show the maintainer comments on cards

## Security Considerations

1. Clients MUST verify event signatures and delegation tokens before allowing modifications
2. Relays MAY implement additional spam prevention measures
3. Relays MAY choose to retain only a few recent versions of board and card events.

## Implementation Notes

To maintain a consistent board state:

1. Clients should handle concurrent updates by:
   - Using the event timestamp to resolve conflicts
   - Maintaining card order within columns

2. For performance, clients can:
   - Cache board and card data locally
   - Use efficient subscription filters when requesting updates

## Client-Relay Communication Example

```javascript
// Subscribe to the cards of a board
{
"kinds": [30302],
"#a": ["30301:<board-creator-pubkey>:<board-d-identifier>"]
}
```