Lemin Kanban

A beautifully designed, production-quality Kanban board for personal task management. Built with Next.js 16, TypeScript, SQLite, and a warm paper-inspired aesthetic.

Documentation

• Architecture - System overview, data flows, auth, error handling
• Feature Matrix - Complete feature catalog by category

What's New in v9.7.0 👥

"The Board Sharing & Mentions Update" - Share boards with other users via invite links. Four roles (Owner, Admin, Editor, Viewer) control who can do what. @Mentions in card descriptions highlight board members. All API routes now use centralized role-based authorization.

See the full changelog on the Releases Page.

Features

Core Features

• Multiple Boards - Create, rename, and delete personal Kanban boards with cover images
• Board & Column Archive - Archive boards and columns instead of deleting them, restore anytime from the archive panel
• Board Ordering - Rearrange boards on the dashboard
• Board Filters - Filter and search boards
• Columns - Default Todo/Doing/Done columns with ability to add, rename, and delete
• Column Dragging - Reorder columns by dragging them directly
• Column Reordering - Move columns left/right with arrow buttons
• Collapsible Columns - Collapse columns to save space, auto-expand on drag
• Column Colors - 7 custom colors (Gray, Yellow, Green, Blue, Purple, Pink, Red)
• Board Sharing - Share boards with other users via invite links with role-based access (Owner, Admin, Editor, Viewer)
• Invite Links - Create invite links with configurable max uses and expiration dates
• @Mentions - Tag board members in card descriptions with accent-colored highlights
• Cards - Full CRUD with title, description, labels, due dates, priorities, and checklists
• Card Priorities - 4 levels (Low, Medium, High, Critical) with color-coded indicators
• Custom Label Colors - Assign one of 10 colors to any label (Red, Orange, Amber, Green, Teal, Blue, Indigo, Purple, Pink, Gray), global per user across all boards
• Card Images - Upload up to 4 images per card (PNG, JPEG, WebP, GIF) with lightbox viewer and copy-to-clipboard
• Subtasks/Checklists - Add task checklists to cards with visual progress bars
• Drag & Drop - Move cards between columns with visual feedback
• WIP Limits - Set per-column Work in Progress limits with color-coded indicators (amber at limit, red over limit)
• Board Zoom - Zoom in/out with buttons, trackpad pinch, or touch gestures (50%-150%)
• UI Zoom - Adjust interface scale (80%-120%) with slider in Settings > Design
• Full Touch Support - Drag cards, pinch to zoom - works great on iPad and mobile
• Keyboard Accessible - Arrow buttons for moving cards without drag & drop, full keyboard shortcut support
• SSE Live Updates - Board changes appear instantly without page reload
• Auto-Reconnect - SSE connection recovers automatically on disconnect or tab switch
• Deploy Notification - Live countdown banner warns users before server restart, auto-reloads when back
• Board Export - Export boards as CSV or JSON for backup or analysis
• Board Import - Import boards from JSON backup files
• Keyboard Shortcuts - Navigate and manage boards with keyboard (press ? for help)
• Activity Log - Track the last 20 events per board
• Search & Filter - Find cards by title, description, or label

Security & Privacy 🔐

• Two-Factor Authentication (TOTP) - Protect your account with any authenticator app (Google Authenticator, Authy, 1Password)
• QR Code & Manual Key Setup - Scan a QR code or enter the secret manually to link your authenticator
• 20 Backup Codes - Single-use recovery codes, individually salted and SHA-256 hashed
• Remember Device - Skip 2FA for 30 days on trusted devices
• AES-256-GCM Secret Encryption - TOTP secrets encrypted at rest with authenticated encryption
• Single-Session Enforcement - Only one active session per account, new logins kick old sessions
• Secure Authentication - Cookie-based sessions with bcrypt password hashing, double password confirmation on registration
• Token Fingerprinting - Session tokens never exposed to client-side JavaScript
• Login Activity Tracking - See who accessed your account and from where
• Failed Login Alerts - Get notified of suspicious login attempts
• Account Deletion - Self-service deletion with 30-day recovery period
• Privacy Policy - Full transparency about data handling
• Rate Limiting - Protection against brute-force attacks

Feedback 💬

• User Feedback - Send feedback directly from the app (up to 5 per user)
• Public Showcase - Admin-published feedback displayed on the landing page with star filters
• Auto-Translation - Feedback is auto-translated to English on publish (Google Translate)
• Admin Replies - Admin can respond to feedback from the admin panel
• Publish Toggle - Admin can publish/unpublish individual feedback from the dashboard
• Inbox Notifications - Users get inbox messages and popups when admin replies
• Admin Notifications - Admin gets inbox messages when new feedback arrives
• Privacy - Only first names shown publicly, never emails; account deletion removes showcase entries

Inbox & Notifications 📬

• Unified Inbox - All your notifications in one place
• Account Updates - Notifications for password, name, and email changes
• Security Alerts - Warnings for failed login attempts
• Feedback Replies - Notifications when admin responds to your feedback
• What's New - In-app release notes and changelog
• Unread Indicators - Visual badges with your accent color

Customization 🎨

• Dark Mode - Full dark theme support with warm tones
• 6 Accent Colors - Orange, Blue, Green, Purple, Rose Pink, Hot Pink
• Custom Label Colors - Long-press a label in the card modal to pick from 10 palette colors; adapts to Light/Dark mode automatically
• Simple Card Design - Option to hide move arrows and delete buttons
• Simple Column Mode - Option to hide column move arrows for cleaner look
• UI Zoom Slider - Scale interface from 80% to 120% for better readability
• Responsive - Works on mobile, tablet, and desktop

MCP Server 🤖

• OAuth 2.1 - Connect Claude Code or Claude.ai with browser-based login (no tokens to copy)
• Dynamic Client Registration - Clients register automatically per RFC 7591
• Token Refresh - Access tokens refresh automatically (1h access, 30d refresh)
• Connection Management - View, rename, and revoke OAuth connections in Settings
• Consent UI - Accept/deny interface for OAuth tool connections
• 24 Tools - Full CRUD for boards, columns, cards, subtasks, activities, label colors, and archive/restore
• Rate Limiting - API protection against too many requests
• Documentation - Setup guide with copy buttons at /docs/mcp

Settings ⚙️

• Account Tab - Update name, email, password (double confirmation) with always-visible save button
• Security Tab - View login history and manage account deletion
• Design Tab - Theme, accent color, and simple card design preferences
• AI Copilot Tab - OAuth connections and Claude integration setup
• Features Tab - Toggle experimental features (Coming soon)
• Credits Tab - Open source acknowledgments and support options (v8.5.0)
• Privacy Tab - Data handling information
• Feedback Tab - Send feedback directly to the admin (up to 5 messages)
• Report Bug Tab - Direct link to GitHub Issues

Tech Stack

• Framework: Next.js 16 (App Router, Turbopack)
• Language: TypeScript (end-to-end)
• Database: SQLite with Prisma ORM
• Styling: Tailwind CSS v4
• Auth: iron-session (cookie-based)
• MCP: mcp-handler + @modelcontextprotocol/sdk
• Drag & Drop: @dnd-kit
• Validation: Zod
• Testing: Vitest (unit) + Playwright (E2E)

Prerequisites

• Node.js 18+ (LTS recommended)
• npm 9+

Installation

# Clone the repository
git clone https://github.com/leminkozey/mini-kanban.git
cd mini-kanban

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and set a secure SESSION_SECRET

# Run database migrations
npm run db:migrate

# Seed demo data (optional)
npm run db:seed

Running the App

# Development server
npm run dev

# Production build
npm run build
npm start

# Open http://localhost:3000

Updating

If you have an existing installation:

# 1. Stop the app

# 2. Backup your database!
cp prisma/dev.db prisma/dev.db.backup

# 3. Pull new code
git pull origin main

# 4. Install dependencies
npm install

# 5. Regenerate Prisma client
npx prisma generate

# 6. Apply database migrations (keeps your data)
npx prisma migrate deploy

# 7. Rebuild
npm run build

# 8. Start
npm start

Important Notes:

• The dev.db file contains all your data - never delete it during updates
• New database fields are added automatically with safe defaults
• Existing users will see a Privacy Policy update popup on first login

Migrating Data from Another Server

# On the OLD server:
cp prisma/dev.db /path/to/backup/dev.db

# Transfer to new server
scp prisma/dev.db user@newserver:/path/to/mini-kanban/prisma/

# On the NEW server:
npx prisma generate
npx prisma migrate deploy
npm run build
npm start

The dev.db file contains:

• All user accounts (emails, passwords, settings)
• All boards, columns, and cards
• Activity logs and notifications
• Login attempt history

Database Commands

npm run db:migrate   # Run migrations
npm run db:push      # Push schema changes (dev)
npm run db:seed      # Seed demo data
npm run db:studio    # Open Prisma Studio (GUI)

Testing

# Unit & Integration Tests
npm test
npm run test:watch

# End-to-End Tests
npm run test:e2e
npm run test:e2e:ui

Project Structure

mini-kanban/
├── prisma/
│   ├── schema.prisma      # Database schema
│   ├── seed.ts            # Demo data seeder
│   └── migrations/        # Database migrations
├── src/
│   ├── app/
│   │   ├── api/           # API route handlers
│   │   ├── board/         # Board view page
│   │   ├── dashboard/     # User dashboard
│   │   ├── login/         # Login page
│   │   ├── register/      # Register page
│   │   ├── privacy/       # Privacy policy page
│   │   ├── docs/mcp/      # MCP documentation page
│   │   └── page.tsx       # Landing page
│   ├── components/
│   │   ├── auth/          # Auth forms
│   │   ├── board/         # Kanban components
│   │   ├── settings/      # Settings modal
│   │   └── ui/            # Reusable UI components
│   ├── hooks/
│   │   ├── useBoardEvents.ts # SSE live update hook
│   │   └── useKeyboardShortcuts.ts # Keyboard shortcuts hook
│   └── lib/
│       ├── auth.ts        # Auth utilities
│       ├── db.ts          # Prisma client
│       ├── event-bus.ts   # SSE event emitter singleton
│       ├── session.ts     # Session config
│       ├── activity.ts    # Activity logging
│       ├── notifications.ts # Notification system
│       ├── privacy.ts     # Privacy policy versioning
│       ├── releases.ts    # Release notes
│       ├── translate.ts   # Google Translate helper
│       ├── label-colors.ts # Label color palette & helpers
│       └── validations.ts # Zod schemas
└── tests/

Demo Account

npm run db:seed

Creates a demo account:

• Email: demo@example.com
• Password: demo123

To remove: sqlite3 prisma/dev.db "DELETE FROM User WHERE email = 'demo@example.com';"

API Endpoints

Auth

• POST /api/auth/register - Create account
• POST /api/auth/login - Login
• POST /api/auth/logout - Logout
• GET /api/auth/me - Get session status & token fingerprint
• POST /api/auth/claim-session - Claim session for current tab
• GET /api/auth/profile - Get current user
• PATCH /api/auth/profile - Update profile & settings
• POST /api/auth/accept-privacy - Accept privacy policy

Boards

• GET /api/boards - List user's boards
• POST /api/boards - Create board
• GET /api/boards/[id] - Get board with columns/cards
• PATCH /api/boards/[id] - Rename board
• DELETE /api/boards/[id] - Delete board
• POST /api/boards/[id]/archive - Archive board
• DELETE /api/boards/[id]/archive - Restore archived board
• GET /api/boards/[id]/archived-columns - List archived columns
• POST /api/columns/[id]/archive - Archive column
• DELETE /api/columns/[id]/archive - Restore archived column
• GET /api/boards/[id]/events - SSE stream for live board updates
• POST /api/deploy-notify - Trigger deploy restart notification
• GET /api/deploy-notify/events - SSE stream for deploy events
• GET /api/boards/[id]/export/csv - Export board as CSV
• GET /api/boards/[id]/export/json - Export board as JSON
• POST /api/boards/import - Import board from JSON

Board Sharing

• GET /api/boards/[id]/shares - List board members
• POST /api/boards/[id]/shares - Add member or create invite link
• PATCH /api/boards/[id]/shares - Update member role
• DELETE /api/boards/[id]/shares - Remove member
• GET /api/boards/[id]/shares/invites - List active invites
• DELETE /api/boards/[id]/shares/invites - Revoke invite
• POST /api/invite/[code] - Redeem invite link

MCP

• POST /api/mcp - MCP endpoint (24 tools: boards, columns, cards, subtasks, activities, label colors, archive/restore)

OAuth 2.1

• GET /.well-known/oauth-protected-resource - Protected Resource Metadata (RFC 9728)
• GET /.well-known/oauth-authorization-server - Authorization Server Metadata (RFC 8414)
• POST /api/oauth/register - Dynamic Client Registration (RFC 7591)
• GET /api/oauth/authorize - Authorization endpoint (redirects to consent page)
• POST /api/oauth/authorize - Process consent (approve/deny)
• POST /api/oauth/token - Token exchange (auth code + refresh token)
• POST /api/oauth/revoke - Token revocation (RFC 7009)
• GET /api/auth/oauth-sessions - List active OAuth connections
• PATCH /api/auth/oauth-sessions - Rename OAuth connection
• DELETE /api/auth/oauth-sessions - Revoke OAuth connection

Card Images

• POST /api/cards/[cardId]/images - Upload image to card
• GET /api/cards/[cardId]/images - Get all images for a card
• DELETE /api/card-images/[id] - Delete an image

Feedback

• GET /api/feedback - Get user's feedback
• POST /api/feedback - Submit feedback (max 5 per user)
• GET /api/feedback/replies - Get replies to user's feedback
• GET /api/public/feedback - Get published feedback (no auth, cached)
• GET /api/admin/feedback - List all feedback (admin only)
• POST /api/admin/feedback/reply - Reply to feedback (admin only)
• PATCH /api/admin/feedback/publish - Publish/unpublish feedback (admin only)

Notifications

• GET /api/notifications - Get user notifications
• PATCH /api/notifications - Mark as read

Account

• POST /api/auth/delete-account - Request account deletion
• POST /api/auth/cancel-deletion - Cancel deletion request
• GET /api/auth/login-attempts - Get login history

Environment Variables

Variable	Description	Default
DATABASE_URL	SQLite database path	file:./prisma/dev.db
SESSION_SECRET	32+ char secret for sessions	Required
COOKIE_SECURE	Set to false for HTTP	true in production
OAUTH_ISSUER_URL	Public URL for OAuth metadata	http://localhost:3000
DEPLOY_SECRET	Secret for deploy notification endpoint	—

Generate a secure secret:

openssl rand -base64 32

Deploy Notification Banner

When you deploy a new version, the server can notify all connected users with a live countdown banner before the restart. Users see "Server restarting in X:XX" with a warning that unsaved changes may be lost. After the countdown, the page automatically reloads when the server is back.

How it works

1. Your CI/CD pipeline sends a POST request to /api/deploy-notify before restarting
2. The server broadcasts the restart timestamp to all connected clients via SSE
3. Clients show a centered banner with a 3-minute countdown
4. After the countdown, clients poll until the server responds and then auto-reload

Setup

1. Generate a deploy secret:

openssl rand -hex 32

2. Add to .env on the server:

DEPLOY_SECRET="your-generated-secret-here"

3. Add to your GitHub Actions deploy workflow (before the restart step):

- name: Notify connected users
  run: |
    curl -s -X POST https://your-domain.com/api/deploy-notify \
      -H "X-Deploy-Secret: ${{ secrets.DEPLOY_SECRET }}" || true

- name: Wait for countdown
  run: sleep 180

- name: Restart server
  run: # your restart command here

4. Add DEPLOY_SECRET to your GitHub repository secrets:

Go to Settings > Secrets and variables > Actions > New repository secret, name it DEPLOY_SECRET with the same value as in .env.

API

Endpoint	Method	Description
/api/deploy-notify	POST	Trigger deploy notification (requires X-Deploy-Secret header)
/api/deploy-notify/events	GET	SSE stream for deploy events (no auth, public)

Testing locally

# 1. Set DEPLOY_SECRET in .env
echo 'DEPLOY_SECRET="test"' >> .env

# 2. Start dev server
npm run dev

# 3. Open browser at http://localhost:3000

# 4. Trigger notification
curl -X POST http://localhost:3000/api/deploy-notify -H "X-Deploy-Secret: test"

# 5. Banner appears with 3:00 countdown

Design Philosophy

The UI uses a warm, paper-inspired aesthetic with:

• Instrument Serif for headings (elegant, editorial)
• DM Sans for body text (clean, modern)
• Warm cream backgrounds with deep ink text
• Colorful column backgrounds (beige, yellow, green)
• 5 customizable accent colors
• Full dark mode with warm tones
• Subtle noise texture for depth
• Smooth animations for delight

Changelog

For the full changelog with all versions, features, and technical details, visit the Releases Page.

License

MIT © 2026 leminkozey

Note: Commercial use of this software requires explicit permission from the author. Personal use and self-hosting are welcome. If you'd like to use this commercially, please reach out via GitHub.

Author

Made with ❤️ by @leminkozey