Kanvana: The Personal Kanban Board to Nirvana

kanvana == "Kanban" + "Nirvana" # smooth flow

Transform your productivity with a sleek, local-first Kanban board. No servers, no tracking—just pure efficiency in your browser.

A beautiful, modern-designed personal, flexible Kanban board + Time Tracker that runs entirely in your browser. No backend, no cloud, no data tracking. Everything stays local with browser IndexedDB persistence. Perfect for personal task management, work tracking, and staying organized.

🚀 Live Demo

Experience it firsthand: Try the Live Demo

✨ Key Features

Time Tracking (New!)

Log time against customers and projects on a dedicated page, opened from the board menu:

• Fast entry: type a description, pick a project, and set start, end or duration using shorthand like 930, 90m or 1.5
• Daily log: entries grouped by day with totals, editable from the keyboard
• Monthly reports: totals, a daily bar chart stacked by project, and a customer/project breakdown
• Projects and settings: archive customers and projects, and choose the date, time, timezone and duration formats
• Syncs: time data syncs to your other signed-in devices

✅ Sub-tasks

Break complex tasks into smaller, trackable steps without leaving the board:

• Inline creation — type a sub-task title and press Enter to add it instantly
• Checkbox completion — check off each step; completed items are struck through and visually muted
• Inline editing — click any sub-task title to edit it in place; press Enter to save or Escape to cancel
• Drag to reorder — grab the handle and drag sub-tasks into the order that makes sense
• Progress indicator — the task card shows a donut circle with completed/total Done count that turns green when everything is done
• Lightweight — sub-tasks have no labels, priorities, or relationships; they stay scoped to their parent task

Sub-tasks are saved with the parent task and survive export/import round-trips. Existing tasks default to zero sub-tasks with no migration needed.

🔗 Task Relationships

Link tasks together to communicate dependencies and connections:

• Prerequisite — another task must be completed before this one can begin
• Dependent — this task is needed by another task before that task can start
• Related — a general connection between two tasks without implying order

Relationships are bidirectional: adding one automatically creates the inverse on the linked task, and removing it cleans up both sides. Search for tasks by short ID (e.g. #ae2ry) or title, view active relationships as color-coded badges in the task modal, and click any badge ID to jump straight to that task.

🏊 Swim Lanes

Organize your board into horizontal swim lanes for a powerful two-dimensional view of your workflow:

• Flexible Grouping: Group tasks by label, label group, or priority — each mode creates distinct swim lane rows
• Drag & Drop Across Lanes: Move tasks between columns, lanes, or both in a single gesture — lane assignments update automatically
• Per-Cell Control: Collapse/expand individual swim lane cells, entire rows, or workflow columns independently
• Quick Task Creation: Add tasks directly to any swim lane cell with automatic label/priority assignment
• Smart Done Column: Done tasks are hidden in swim lanes to keep rows compact, while the Done column remains a drag-and-drop target
• Sticky Headers: Lane headers stay pinned during horizontal scrolling; workflow headers stay visible during vertical scrolling
• Mobile Optimized: Responsive flex layout with sticky lane headers and snap-scrolling columns on mobile
• Persistent State: All swim lane settings, collapsed states, and lane assignments are saved per board

Configure swim lanes in Settings or use the quick-access toggle in the board controls menu. Lane order is customizable via drag-and-drop in Settings.

🔄 Real-Time Multi-Device Sync

Edit on your phone, see it on your laptop — within seconds. Kanvana uses event-sourced sync: every change is a domain event ordered by a Hybrid Logical Clock (HLC), so independent edits across devices converge without overwriting each other. Tasks, columns, and labels in your browser are projections rebuilt from the event stream.

• Opt-in, never required — stays 100% local until you choose to sign in. No account, no cloud, no problem.
• Live across devices — an optional PocketBase backend streams remote changes over Server-Sent Events in real time; a catch-up pull on launch means a just-opened device is immediately up to date.
• At-a-glance sync indicator — the header shows Live ● (synced), Syncing… (N) (events draining), ⚠ N unsynced (retrying), or Offline (no network / signed out).
• Offline-first, always — the fully-offline experience is never compromised; the cloud is just an optional fan-out, not a dependency.

Core Features

• 🔗 Clickable URLs in Descriptions: Paste any http:// or https:// link into a task description and it becomes a clickable link on the card — opens in a new tab, no page refresh. A live link preview strip also appears below the description field in the task modal as you type, so you can click URLs without saving first
• ⌨️ Keyboard Shortcuts: Move quickly through board management and task editing with context-aware keybindings. Ctrl+B opens Manage Boards, Escape closes active modals and menus, arrow keys navigate board and label lists, and Enter activates focused choices. Shortcuts are form-safe, so typing in inputs does not accidentally trigger global actions. See the full keyboard shortcuts table.
• 🚀 Blazing Fast & Simple: Lightning-quick performance with a clean, intuitive interface
• 🔍 Powerful Search: Find tasks instantly by label, title, description, or label groups
• 📊 Productivity Reports: Visualize your progress with Cumulative Flow Diagrams, weekly lead time, completion stats, same-day completions tracking, and an activity heatmap covering the last 365 days
• 📅 Calendar View: See tasks by due date on a monthly calendar with overdue highlighting
• 🔔 Smart Notifications: Get reminded of due dates with customizable advance notices and color-coded countdown timers (urgent/warning thresholds)
• 💻 Local-First: Works fully offline with no backend required — your data lives in your browser and never leaves your device unless you opt into Real-Time Multi-Device Sync
• 🎨 Drag & Drop: Effortlessly move tasks and columns with optimized performance (handles 300+ tasks)
• 🏷️ Custom Labels & Colors: Organize with personalized labels, groups, and column colors — label text automatically switches between black and white for readability
• 📋 Multiple Boards: Create and manage multiple boards with board templates
• 💾 Easy Backup: Export/import boards as JSON via Manage Boards — save backups to your favorite cloud storage (OneDrive, Google Drive, Dropbox)
• 📱 Fully Responsive: Optimized for mobile and desktop — work from anywhere
• 🌗 Light & Dark Theme: Toggle between themes with automatic persistence
• : Collapse columns to save space while still accepting drag-and-drop

📸 Screenshots

🛡️ Data Security & Persistence

Your data is stored securely in your browser's IndexedDB. It persists across sessions and page reloads. For extra safety, use the built-in export feature to save backups to your preferred cloud storage.

If you opt into Real-Time Multi-Device Sync, your event stream is also synced to a PocketBase backend so the same boards stay in step across your devices. Sync is entirely optional — without an account, nothing leaves your browser.

🚀 Quick Start

Get up and running in minutes!

For Users: Try It Now

1. Visit the Live Demo.
2. Start creating boards, tasks, and labels immediately.
3. Export your data anytime for backup.

For Developers: Host Your Own

The repository includes a pre-built static site in dist/. Simply upload it to any web host.

1. Copy the dist/ folder.
2. Upload to your web host (e.g., Hetzner, Netlify, Vercel).
3. Done! Your Kanvana achieved and the Kanban board is live.

🛠️ Development

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repo:

   git clone https://github.com/mdiener21/kanvana.git
   cd kanvana
   

2. Install dependencies:

   cd client
   npm install
   

3. Start the dev server:

   cd client
   npm run dev
   

   The app will open at http://localhost:3000.

Build for Production

cd client
npm run build

Built files are in client/dist/.

Preview Production Build

cd client
npm run preview

Releasing a New Version

Releases are fully automated via GitHub Actions — no local commands needed.

Step 1 — Keep CHANGELOG.md up to date during development

As you merge features and fixes, add bullet points under ## [Unreleased] in CHANGELOG.md. Use the standard sections:

## [Unreleased]

### Added
- Some new feature

### Fixed
- Some bug fix

This is a normal commit — not a release trigger.

Step 2 — Trigger "Generate Release" on GitHub

1. Go to Actions → Generate Release → Run workflow
2. Fill in the two inputs:
   • Version bump type — patch (bug fixes), minor (new features), or major (breaking changes)
   • Skip tests — leave unchecked to run the full test suite first (recommended); check to force a release without tests
3. Click Run workflow

The workflow runs in two jobs:

• Run tests — executes unit, DOM, and Playwright E2E tests (Firefox). If any test fails the workflow stops and no PR is created. Fix the failure and re-trigger. If Skip tests was checked this job is skipped entirely.
• Create release PR — only runs when tests passed or were deliberately skipped. Bumps package.json, promotes ## [Unreleased] to a dated release section in CHANGELOG.md, updates the README version badge, and opens a pull request. The PR body clearly shows whether tests passed or were skipped.

Step 3 — Review and merge the PR

Check that the changelog and version look correct, then merge the pull request. If the PR body shows tests were skipped, decide whether that is acceptable before merging.

Step 4 — Done

Merging triggers the Publish Release workflow automatically. It reads the version from package.json, creates and pushes the git tag, and publishes the GitHub Release with the changelog notes. No further action needed.

If your repo blocks Actions from creating PRs, enable: Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests.

Run Tests

This project uses a four-layer test stack:

• Vitest for pure unit tests in tests/unit/
• Vitest + @testing-library/dom for DOM integration tests in tests/dom/
• MSW for mocked API behavior shared by Vitest suites from tests/mocks/
• Playwright for end-to-end and visual/accessibility smoke coverage in tests/e2e/

Run the full automated test stack:

npm test

Run only the unit tests:

npm run test:unit

Run only the DOM integration tests:

npm run test:dom

Run only the Playwright E2E tests:

npm run test:e2e

Run only the create-task E2E tests (tests/e2e/create-task.spec.ts):

npm run test:e2e -- tests/e2e/create-task.spec.ts

The detailed strategy, folder layout, and naming convention live in docs/testing-strategy.md.

📚 Documentation

Dive deeper with our comprehensive docs: View Documentation

🤝 Contributing

We love contributions! Whether it's bug fixes, features, or docs—every star and fork helps grow the community.

• Star this repo ⭐ to show your support!
• Fork and contribute code or ideas.
• Report issues for bugs or suggestions.

📄 License

Licensed under the MIT License. See LICENSE.md for details.

---

Made with ❤️ for productivity enthusiasts. Star us on GitHub to stay updated!