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
eingang (inbox)	FUTURE	Backlog items, ideas, future phases
in planung (planning)	PENDING	Ready to implement, needs detailed specs
in arbeit (in progress)	IN PROGRESS (🔄)	Currently working on
erledigt (done)	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
• GET /boards/{boardId}/stacks - Get stacks
• POST /boards/{boardId}/stacks/{stackId}/cards - Create card

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"

• Nextcloud Deck version may have different API
• Check Nextcloud Deck version in settings
• Some GET endpoints may not be available

"Cards not syncing"

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

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 arbeit',
    'YOUR_STATUS': 'your_stack',  # Add here
}