Hadoku Task Manager

A minimalist, portable task tracking micro-frontend

Live at: https://hadoku.me/task/

Fast, focused task management with tags, filtering, and multi-user support. Built as a reusable micro-frontend with framework-agnostic API handlers. Perfect for embedding in larger applications or using standalone.

---

📱 Mobile App (Android)

Native Android app available! Built with Capacitor WebView wrapper.

Quick Download:

• 📥 Latest APK
• 🔄 Obtainium: Install Obtainium, then add URL: https://github.com/WolffM/hadoku-task-mobile

Repository: hadoku-task-mobile

---

✨ Features

• ⚡ Quick Task Entry - Type and press Enter
• 🏷️ Tag Support - Organize with #tags
• 🔍 Smart Filtering - Filter by tag or view all
• 🎯 Drag & Drop - Reorder tasks and move between boards
• 🎨 9 Theme Families - Light, Dark, Strawberry, Ocean, Cyberpunk, Coffee, Lavender, Nature, Pink, Izakaya
• 📋 Multi-Board - Organize tasks across multiple boards
• ⚡ Optimistic Updates - Instant UI response with background sync
• 👥 Multi-User - Public (localStorage), Friend/Admin (server sync)
• 🔌 Framework Agnostic - Pure handlers work with any backend

---

🚀 Quick Start

Install and Run

pnpm install
pnpm run dev
# Open http://localhost:5173?userType=public

Test

pnpm run test:worker         # worker harnesses against a real SQLite D1
pnpm run dev:api             # required by the server-backed e2e specs
pnpm exec playwright test    # ~110 e2e specs

CI runs typecheck, lint and test:worker — not Playwright — so a green build is not evidence the e2e suite passes. Run it locally, with dev:api up, or ~33 specs skip themselves and the counts quietly look fine.

Build for Production

pnpm run build:all

Output:

• Client: dist/index.js (~54KB gzipped), dist/style.css (~15KB gzipped)
• Handlers: dist/server/ (TypeScript compiled to JavaScript)

---

📦 Installation

As an NPM Package

npm install @wolffm/task

Basic Integration

Client-side:

import { mount } from '@wolffm/task/frontend'
import '@wolffm/task/style.css'

mount(document.getElementById('app'), {
  userType: 'public',
  sessionId: 'session-123'
})

Server-side (framework-agnostic):

import { TaskHandlers, TaskStorage } from '@wolffm/task/api'

// Implement storage for your environment (KV, filesystem, database, etc.)
const storage: TaskStorage = {
  getTasks: async userType => {
    /* your implementation */
  },
  saveTasks: async (userType, tasks) => {
    /* your implementation */
  },
  getStats: async userType => {
    /* your implementation */
  },
  saveStats: async (userType, stats) => {
    /* your implementation */
  }
}

// Use handlers with any framework (Express, Hono, Cloudflare Workers, etc.)
const tasks = await TaskHandlers.getTasks(storage, auth)
const newTask = await TaskHandlers.createTask(storage, auth, { title: 'Task' })

---

💡 Usage

Creating Tasks

Buy groceries [Enter]                    # Plain task
Buy groceries #home [Enter]              # With tag
Fix bug #high-priority [Enter]           # Tagged task

Task Actions

• ✓ Mark complete
• × Delete task
• ✎ Edit title
• + Add tag
• Drag Reorder or move between boards

Themes

Choose from 9 theme families via the theme picker (top-right), each with light and dark variants:

• ☼ Light / ☽ Dark - Clean and sophisticated defaults
• ❖ Strawberry - Sweet pink tones
• ≈ Ocean - Deep sea blues
• ◆ Cyberpunk - Neon dystopia
• ◉ Coffee - Rich espresso
• ✿ Lavender - Soft purple
• 🌿 Nature - Lush forest greens
• 💗 Pink - Bubblegum vibes
• 🏮 Izakaya - Cozy Japanese bar aesthetic

---

📚 Documentation

Document	Purpose	Audience
ARCHITECTURE.md	System design, patterns, technical decisions	Developers integrating or extending
API.md	Complete endpoint reference	Backend implementers
MCP.md	Remote MCP server for agents (tasks/calendar)	Agents & integrators
CHANGELOG.md	Version history and changes	All users
CONTRIBUTING.md	Contribution guidelines	Contributors

Quick Links

• Getting Started: You're reading it! (README.md)
• How it works: Architecture Overview
• Security model: Authentication & Security
• API endpoints: Complete API Reference
• Agents / MCP: MCP Server
• Add features: Contributing Guide

---

🏗️ Architecture Highlights

Universal Adapter Pattern

This package separates pure business logic from framework-specific code:

// Handlers are pure functions - work with ANY framework
await TaskHandlers.getTasks(storage, auth)
await TaskHandlers.createTask(storage, auth, input)

Deployment flexibility:

• ✅ Cloudflare Workers (KV storage)
• ✅ Node.js + Express (filesystem storage)
• ✅ Any framework that can call JavaScript functions

Client Architecture

• React-based UI with optimistic updates
• All user types use localStorage for instant feedback
• Non-public users sync to server in background
• 9 theme families (18 themes) with CSS custom properties

See ARCHITECTURE.md for detailed design documentation.

---

🔐 Security & Authentication

This micro-frontend delegates authentication to the parent application.

The task app:

• ✅ Does NOT handle credentials or passwords
• ✅ Receives userType and sessionId from parent
• ✅ Uses these for storage namespacing only

Your parent app must:

• ✅ Handle user login/logout
• ✅ Validate authentication keys
• ✅ Provide correct userType and sessionId
• ✅ Secure API endpoints

See ARCHITECTURE.md - Security for complete security model.

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development workflow
• Code style guidelines
• How to add features
• Pull request process

---

📝 License

MIT License - see LICENSE for details.

---

🔗 Links

• Web Repository: https://github.com/WolffM/hadoku-task
• Mobile Repository: https://github.com/WolffM/hadoku-task-mobile
• Example Deployment: hadoku.me/task
• NPM Package: @wolffm/task
• Android APK: Latest Release

---

Author: WolffM