Lemin Kanban
A minimal, beautifully designed Kanban board for personal task management. Built with Next.js, TypeScript, and SQLite.
Installation
npx lemin-kanbanAsk AI about Lemin Kanban
Powered by Claude Β· Grounded in docs
I know everything about Lemin Kanban. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.dbfile 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 accountPOST /api/auth/login- LoginPOST /api/auth/logout- LogoutGET /api/auth/me- Get session status & token fingerprintPOST /api/auth/claim-session- Claim session for current tabGET /api/auth/profile- Get current userPATCH /api/auth/profile- Update profile & settingsPOST /api/auth/accept-privacy- Accept privacy policy
Boards
GET /api/boards- List user's boardsPOST /api/boards- Create boardGET /api/boards/[id]- Get board with columns/cardsPATCH /api/boards/[id]- Rename boardDELETE /api/boards/[id]- Delete boardPOST /api/boards/[id]/archive- Archive boardDELETE /api/boards/[id]/archive- Restore archived boardGET /api/boards/[id]/archived-columns- List archived columnsPOST /api/columns/[id]/archive- Archive columnDELETE /api/columns/[id]/archive- Restore archived columnGET /api/boards/[id]/events- SSE stream for live board updatesPOST /api/deploy-notify- Trigger deploy restart notificationGET /api/deploy-notify/events- SSE stream for deploy eventsGET /api/boards/[id]/export/csv- Export board as CSVGET /api/boards/[id]/export/json- Export board as JSONPOST /api/boards/import- Import board from JSON
Board Sharing
GET /api/boards/[id]/shares- List board membersPOST /api/boards/[id]/shares- Add member or create invite linkPATCH /api/boards/[id]/shares- Update member roleDELETE /api/boards/[id]/shares- Remove memberGET /api/boards/[id]/shares/invites- List active invitesDELETE /api/boards/[id]/shares/invites- Revoke invitePOST /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 connectionsPATCH /api/auth/oauth-sessions- Rename OAuth connectionDELETE /api/auth/oauth-sessions- Revoke OAuth connection
Card Images
POST /api/cards/[cardId]/images- Upload image to cardGET /api/cards/[cardId]/images- Get all images for a cardDELETE /api/card-images/[id]- Delete an image
Feedback
GET /api/feedback- Get user's feedbackPOST /api/feedback- Submit feedback (max 5 per user)GET /api/feedback/replies- Get replies to user's feedbackGET /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 notificationsPATCH /api/notifications- Mark as read
Account
POST /api/auth/delete-account- Request account deletionPOST /api/auth/cancel-deletion- Cancel deletion requestGET /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
- Your CI/CD pipeline sends a POST request to
/api/deploy-notifybefore restarting - The server broadcasts the restart timestamp to all connected clients via SSE
- Clients show a centered banner with a 3-minute countdown
- 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
