trading_bot_v4/docs/NEXTCLOUD_DECK_SYNC.md

Nextcloud Deck Roadmap Sync

Bidirectional sync system between trading bot roadmaps (markdown files) and Nextcloud Deck kanban board.

Setup

1. Discover Board Configuration

First time setup - find your Nextcloud Deck board and stack IDs:

./scripts/discover-deck-ids.sh

This creates /tmp/deck-config.json with your board configuration.

2. Initialize Deck with Roadmap Cards

Create Deck cards from current roadmap:

python3 scripts/sync-roadmap-to-deck.py --init

This will:

• Parse all roadmap files (OPTIMIZATION_MASTER_ROADMAP.md, etc.)
• Create cards for each initiative/phase
• Place cards in appropriate stacks based on status
• Set due dates based on timelines

Stack Mapping

Deck Stack	Roadmap Status	Purpose
📥 Backlog	FUTURE	Backlog items, ideas, future phases
📋 Planning	PENDING	Ready to implement, needs detailed specs
🚀 In Progress	IN PROGRESS (🔄)	Currently working on
✅ Complete	COMPLETE (✅)	Finished and verified

Usage

Creating Roadmap Cards

Option 1: Update markdown, sync to Deck

1. Edit roadmap markdown files
2. Run: python3 scripts/sync-roadmap-to-deck.py --init
3. New initiatives/phases appear as Deck cards

Option 2: Create card in Deck (future feature)

1. Create card in Deck "eingang" stack
2. Title format: [ROADMAP] Initiative Name
3. Script will parse and add to appropriate roadmap file

Updating Status

Current: Manual sync

• Move cards between stacks in Deck to reflect progress
• Update markdown roadmap files with status emoji (🔄, ✅, etc.)
• Re-sync to align

Future: Automatic bidirectional sync

• Script will update roadmap files based on card positions
• Cron job could run sync every hour

Files

• scripts/discover-deck-ids.sh - Find board/stack IDs
• scripts/sync-roadmap-to-deck.py - Main sync script
• /tmp/deck-config.json - Nextcloud configuration (auto-generated)

Configuration

Edit /tmp/deck-config.json or set environment variables:

export NEXTCLOUD_URL="http://10.0.0.48:8089"
export NEXTCLOUD_USER="robert.wiegand"
export NEXTCLOUD_PASSWORD="your-password"

Roadmap Files

Currently syncs:

• OPTIMIZATION_MASTER_ROADMAP.md - Main overview
• SIGNAL_QUALITY_OPTIMIZATION_ROADMAP.md - Initiative 1
• POSITION_SCALING_ROADMAP.md - Initiative 2
• ATR_BASED_TP_ROADMAP.md - Initiative 3

Future Features

• Bidirectional sync (Deck → Roadmap updates)
• Manual card creation → roadmap entry
• Automated sync via cron
• Phase-level cards (not just initiative-level)
• Label management (optimization, data-collection, analysis)
• Due date calculations from timeline estimates
• Progress tracking from card checklists

API Reference

Nextcloud Deck API: /index.php/apps/deck/api/v1.0

Key endpoints used:

• GET /boards - List all boards
• GET /boards/{boardId} - Get board details with stacks (no cards included)
• GET /boards/{boardId}/stacks/{stackId} - Get stack with cards (this works!)
• POST /boards/{boardId}/stacks/{stackId}/cards - Create card
• PUT /boards/{boardId}/stacks/{stackId} - Rename stack

Note: Many endpoints return 405 Method Not Allowed:

• GET /boards/{boardId}/stacks/{stackId}/cards - Not supported
• DELETE /boards/{boardId}/cards/{cardId} - Not supported
• GET /boards/{boardId}/cards/{cardId} - Not supported

Known Limitations

1. No Duplicate Detection: The Deck API v1.0 doesn't support listing cards by stack, so:

   • Running --init multiple times creates duplicate cards
   • Delete duplicates manually from the Nextcloud Deck UI
   • Always use --dry-run first to preview changes

2. No Card Deletion API: The DELETE endpoint returns 405, so:

   • Test cards must be deleted manually from the web UI
   • No automated cleanup possible

3. Limited GET Support: Most card-level GET endpoints return 405:

   • Cannot verify card creation without checking full stack
   • Use GET /boards/{boardId}/stacks/{stackId} to view cards

4. No Bidirectional Sync: Card position changes in Deck don't update markdown files

5. Initiative-Level Only: Currently only syncs high-level initiatives, not individual phases

Troubleshooting

"Board not found"

• Run discover-deck-ids.sh first
• Check board exists in Nextcloud Deck
• Verify name contains "trader" (case insensitive)

"405 Method Not Allowed"

• Normal for most GET/DELETE card endpoints
• Use stack endpoint instead: GET /boards/{boardId}/stacks/{stackId}
• Check Nextcloud Deck API documentation for your version

"Cards not showing in board"

• Cards ARE created but not visible in GET /boards/{boardId} response
• Use GET /boards/{boardId}/stacks/{stackId} to view cards properly
• Or check the Nextcloud Deck web UI

"Cards not syncing"

• Check /tmp/deck-config.json exists
• Verify credentials in config
• Run with --dry-run first to test

"Duplicate cards"

• This is expected - API doesn't support duplicate checking
• Delete extras manually from Nextcloud Deck UI
• Always run --dry-run before --init

Development

Adding new roadmap files:

Edit sync-roadmap-to-deck.py:

ROADMAP_FILES = [
    'OPTIMIZATION_MASTER_ROADMAP.md',
    'YOUR_NEW_ROADMAP.md',  # Add here
]

Customizing status mapping:

Edit STATUS_TO_STACK dict:

STATUS_TO_STACK = {
    'IN PROGRESS': '🚀 In Progress',
    'YOUR_STATUS': '📋 Your Stack',  # Add here (with emoji)
}