FlowBoard - Local Kanban Board Application

A professional-grade, locally-hosted Kanban board application designed for fast, keyboard-driven project management. FlowBoard provides comprehensive task management with a clean, modern interface for organizing work across customizable statuses.

Features

• Workspace & Project Management: Organize multiple projects across workspaces
• Kanban Board: Visual board with drag-and-drop functionality
• List View: Powerful table view with sorting, filtering, and grouping
• Rich Issue Management: Full markdown support, labels, priorities, estimates, due dates
• Comments & Activity Tracking: Complete activity timeline for all changes
• File Attachments: Upload and manage files with image previews
• Keyboard Shortcuts: Fast, keyboard-driven navigation and actions
• Auto-refresh: Real-time updates with smart polling
• Import/Export: CSV and JSON support, compatible with Jira/Linear
• Themes: Light, dark, and system auto-detect
• REST API: Full API access for programmatic control

Tech Stack

Frontend

• React 18+ with Vite
• Tailwind CSS for styling
• TanStack Query for data fetching
• React Router v6
• @dnd-kit for drag and drop
• React Markdown with syntax highlighting

Backend

• Node.js with Express
• SQLite with better-sqlite3
• Zod for validation
• Swagger UI for API documentation

Quick Start

Prerequisites

• Node.js 18+
• npm 9+

Installation

# Install globally
npm install -g flowboard

# Start the server
flowboard serve

For detailed production setup instructions, see DEPLOYMENT.md.

Development Setup

# Clone the repository
git clone <repository-url>
cd flowboard

# Run the setup and development script
./init.sh

The script will:

1. Check for required dependencies
2. Install all npm packages
3. Create necessary directories
4. Start both frontend and backend servers

Access the application:

• Frontend: http://localhost:5173
• API: http://localhost:3847
• API Documentation: http://localhost:3847/api-docs

Manual Setup

If you prefer to set up manually:

# Install dependencies
npm install
cd client && npm install && cd ..
cd server && npm install && cd ..

# Start development servers (frontend + backend)
npm run dev

# Or start them separately
npm run dev:client  # Frontend only
npm run dev:server  # Backend only

CLI Commands

FlowBoard provides a comprehensive CLI for managing your installation:

# Initialize configuration (interactive)
flowboard init

# Start the server
flowboard serve

# Start on custom port
flowboard serve --port 4000

# Use custom database location
flowboard serve --db-path /path/to/flowboard.db

# View version
flowboard --version

# Get help
flowboard --help

Systemd Service Management (Linux)

# Install as systemd service
sudo flowboard service install

# Start/stop/restart service
sudo flowboard service start
sudo flowboard service stop
sudo flowboard service restart

# Check service status
flowboard service status

# View logs
flowboard service logs
flowboard service logs -f  # Follow logs

# Uninstall service
sudo flowboard service uninstall

Configuration

FlowBoard can be configured via multiple methods (in priority order):

1. CLI arguments (highest priority)
2. Environment variables
3. Configuration file (~/.flowboard/config.json)
4. Default values (lowest priority)

Interactive Configuration

Run flowboard init to interactively configure:

• Server port
• Database path
• Uploads directory

The configuration is saved to ~/.flowboard/config.json.

Environment Variables

• PORT: API server port (default: 3847)
• DB_PATH: SQLite database file path (default: ~/.flowboard/flowboard.db)
• UPLOADS_PATH: Attachments storage path (default: ~/.flowboard/uploads)
• CONFIG_PATH: Path to config file (optional)

Configuration File

Edit ~/.flowboard/config.json directly:

{
  "server": {
    "port": 3847,
    "host": "0.0.0.0"
  },
  "database": {
    "path": "/home/user/.flowboard/flowboard.db"
  },
  "storage": {
    "uploadsPath": "/home/user/.flowboard/uploads",
    "maxFileSize": 10485760
  },
  "ui": {
    "refreshInterval": 30000,
    "theme": "system",
    "compactMode": false
  },
  "backup": {
    "path": "/home/user/.flowboard/backups"
  }
}

Keyboard Shortcuts

Global

• C - Create new issue
• Cmd/Ctrl + K - Command palette/search
• Cmd/Ctrl + O - Workspace switcher
• / - Focus search
• ? - Show keyboard shortcuts
• Cmd/Ctrl + R - Manual refresh

Navigation

• B - Go to board view
• L - Go to list view
• Arrow Up/Down - Navigate issues
• Enter - Open selected issue
• Esc - Close modal/panel

Issue Actions (when selected)

• A - Set assignee
• P - Change priority
• S - Change status
• L - Add label
• E - Edit issue
• D - Set due date
• Delete - Archive issue

Editing

• Cmd/Ctrl + Enter - Save and close
• Esc - Cancel without saving
• Cmd/Ctrl + B - Bold (in markdown)
• Cmd/Ctrl + I - Italic (in markdown)

API Usage

FlowBoard provides a full REST API for programmatic access.

# Health check
curl http://localhost:3847/api/v1/health

# Get workspaces
curl http://localhost:3847/api/v1/workspaces

# Create an issue
curl -X POST http://localhost:3847/api/v1/projects/:projectId/issues \
  -H "Content-Type: application/json" \
  -d '{"title": "New task", "priority": "high"}'

Full API documentation available at: http://localhost:3847/api-docs

Backup & Restore

# Create backup
npm run backup

# Create backup to custom location
npm run backup -- --output /path/to/backup.tar.gz

# Restore from backup
npm run restore -- /path/to/backup.tar.gz

Project Structure

flowboard/
├── client/                 # React frontend (Vite)
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Page components
│   │   ├── hooks/          # Custom React hooks
│   │   ├── api/            # API client functions
│   │   └── utils/          # Utility functions
│   └── package.json
├── server/                 # Express backend
│   ├── src/
│   │   ├── routes/         # API route handlers
│   │   ├── models/         # Database models
│   │   ├── middleware/     # Express middleware
│   │   ├── utils/          # Utility functions
│   │   └── database/       # SQLite setup and migrations
│   └── package.json
├── data/                   # SQLite database location
├── uploads/                # File attachments storage
├── feature_list.json       # Complete feature test checklist
└── init.sh                 # Setup and development script

Development Progress

This project uses feature_list.json as the single source of truth for development progress. The file contains 200+ detailed test cases covering all features. As features are implemented and tested, their passes status is updated from false to true.

To check progress:

# Count total features
cat feature_list.json | grep '"passes"' | wc -l

# Count passing features
cat feature_list.json | grep '"passes": true' | wc -l

# Count remaining features
cat feature_list.json | grep '"passes": false' | wc -l

Contributing

This is a single-developer project built iteratively across multiple sessions. Each session:

1. Reviews feature_list.json to determine next priorities
2. Implements features with production-quality code
3. Tests thoroughly before marking features as passing
4. Commits progress with clear messages
5. Updates claude-progress.txt with session summary

License

[License information to be added]

Support

For issues, questions, or contributions, please refer to the project repository.