Mark Board

A visual kanban board application that manages tasks using markdown files organized in folders.

Features

Core Functionality

• 📁 File-based storage with markdown files
• 🔄 Real-time file system synchronization
• 🖱️ Drag and drop cards between columns
• ✏️ Modal-based card creation and editing
• 🏷️ Support for tags, assignees, and due dates
• 🔍 Advanced search and filtering by title, content, tags, and assignees
• 🎨 Dark/light theme support with system preference detection

AI-Powered Features

• 🤖 AI-powered user story co-creator with chat interface
• 🔄 One-click card editing with AI assistance
• 📝 Live markdown preview and formatting shortcuts
• 💬 Context-aware AI conversations with automatic card context loading
• 🔗 Support for multiple AI providers (OpenRouter & OpenAI)
• 🧠 Access to premium models like Claude 3.5 Sonnet via OpenRouter
• ⚙️ Configurable AI integration with environment-based provider selection

Keyboard & Navigation

• ⌨️ Comprehensive keyboard shortcuts (n, e, Delete, arrows, Esc)
• 🎯 Command palette with Cmd+K (Ctrl+K) activation
• 🗂️ Quick card navigation and selection from command palette
• 🗑️ Delete any card with confirmation from command palette
• ✏️ Create new cards via command palette
• 🐧 VIM-style navigation (j/k for up/down, h for back)
• 📜 Auto-scrolling in card selection lists

Performance & UX

• ⚡ Optimized rendering with React.memo and useMemo
• 🔄 Debounced search and file operations
• 🎯 Smooth scrolling and keyboard navigation
• 📱 Responsive design for different screen sizes

Getting Started

Prerequisites

• Node.js 18+ and bun

Installation

bun install

Development

bun run dev

Build

bun run build

Preview Production Build

bun run preview

AI Features

Mark Board includes powerful AI-assisted features for creating and refining user stories:

🤖 Co-Creator Page

• AI Chat Interface: Interactive chat with AI for generating and refining user stories
• Prompt Templates: Pre-built templates for user stories and acceptance criteria
• Live Markdown Editor: Real-time preview with formatting shortcuts
• Conversation Persistence: Save and resume AI conversations
• Export to Board: Create new cards or update existing ones directly from the editor

🔄 Card Integration

• One-Click Editing: Click the 🤖 icon on any card to open it in the co-creator
• Pre-loaded Content: Existing card data is automatically loaded into the editor
• Enhanced AI Context: AI automatically receives card title, content preview, and metadata when editing
• Smart Conversations: AI immediately understands the specific card being worked on
• Seamless Workflow: Move between board view and AI editing effortlessly

⚙️ Configuration

Mark Board supports multiple AI providers for enhanced flexibility and access to premium models:

Option 1: OpenRouter (Recommended)

OpenRouter provides access to premium models like Claude 3.5 Sonnet, GPT-4, and others through a unified API.

1. Create a .env file in the project root:

   touch .env

2. Add your OpenRouter API key:

   VITE_OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key-here
   

Option 2: OpenAI (Legacy Support)

Traditional OpenAI integration for GPT models.

1. Add your OpenAI API key to the .env file:

   VITE_OPENAI_API_KEY=sk-your-openai-key-here
   

Priority & Fallback

• OpenRouter takes priority if both API keys are configured
• Falls back to OpenAI if OpenRouter is not available
• Falls back to mock mode if neither is configured

Smart Provider Selection

The application automatically detects available providers and selects the best option:

1. OpenRouter (Premium models, Claude 3.5 Sonnet)
2. OpenAI (GPT models for compatibility)
3. Mock Mode (Demonstration without API calls)

Security Note: The .env file is already in .gitignore to prevent accidental commits of your API keys.

Restart Required: After adding API keys, restart the development server:

bun run dev

🎨 Theme Behavior

Mark Board automatically detects and follows your system's light/dark preference on first visit. The theme will also update live when you change your OS preference, unless you've manually toggled the theme. Manual theme choices are saved and take precedence over system settings.

Project Structure

mark-board/
├── src/
│   ├── components/     # React components
│   │   ├── Board.tsx   # Main kanban board
│   │   ├── Card.tsx    # Individual cards with AI integration
│   │   ├── CoCreator.tsx # AI-powered story editor with context
│   │   ├── ChatInterface.tsx # AI chat component with provider support
│   │   └── ...
│   ├── hooks/          # Custom React hooks
│   ├── utils/          # Utility functions
│   │   ├── aiService.ts # Multi-provider AI service (OpenRouter/OpenAI)
│   │   └── ...
│   ├── stores/         # State management
│   ├── types/          # TypeScript type definitions
│   │   ├── ai.ts       # AI-related types and templates
│   │   └── ...
│   └── types.ts        # Main type definitions
├── kanban-data/        # Markdown files storage
│   ├── backlog/        # New user stories
│   ├── in-progress/    # Active work
│   └── done/           # Completed items
└── public/             # Static assets

Markdown File Format

Cards are stored as markdown files with YAML frontmatter:

---
title: Card Title
created: 2024-01-01T00:00:00Z
updated: 2024-01-01T00:00:00Z
tags: [feature, backend]
assignee: John Doe
dueDate: 2024-01-15
---

# Card Title

Card content with full markdown support.

## Checklist

- [ ] Task 1
- [ ] Task 2

License

MIT