npm package: @subedigaurab/flowboard
Description: Professional-grade local Kanban board application with CLI, systemd integration, and full-stack architecture
Author: SubediGaurab
Latest version: 1.0.0

# 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

```bash
# Install globally
npm install -g flowboard

# Start the server
flowboard serve
```

For detailed production setup instructions, see [DEPLOYMENT.md](DEPLOYMENT.md).

### Development Setup

```bash
# 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:

```bash
# 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:

```bash
# 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)

```bash
# 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:

```json
{
  "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.

```bash
# 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

```bash
# 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:
```bash
# 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.