Tududi - Developer Guide

This documentation is designed for AI assistants and developers working with the tududi codebase. For user-facing documentation, see README.md. For contribution guidelines, see CONTRIBUTING.md.

Quick Start

Tududi is a self-hosted task management system with hierarchical organization (Areas > Projects > Tasks), smart recurring tasks, and multi-channel integration.

Tech Stack: React 18 + TypeScript, Express + Sequelize, SQLite

Get Started:

git clone https://github.com/chrisvel/tududi.git
cd tududi
npm install
npm run db:init
npm start  # Frontend on :8080, Backend on :3002

Documentation Index

Core Documentation

Architecture Overview
- Tech stack details
- Request flow diagram
- Data model hierarchy
- Authentication methods
Directory Structure
- Complete file tree with absolute paths
- Critical paths reference
- Backend and frontend organization
Backend Patterns
- Module architecture pattern
- How to add new modules
- Module communication
- Repository and service patterns
Database & Migrations
- Key models and relationships
- Migration workflow
- Migration best practices
- Common migration operations
Backups & Restoration
- Automatic SQLite file backups before migrations
- Backup retention policies (4 per day, 1 per day for 7 days)
- Restoration procedures for development, Docker, and production
- Emergency restore after failed migrations
- Best practices for data safety
Development Workflow
- Initial setup
- Daily development (two-server process)
- Environment variables
- Adding new features (complete walkthrough)
- Database management commands
Code Conventions
- Language usage (TypeScript/JavaScript)
- Backend patterns (async/await, repository)
- Frontend patterns (components, state)
- Naming conventions
- API route conventions
Testing
- Test organization
- Running tests
- Testing requirements
- Test patterns (Arrange-Act-Assert)
Common Tasks
- Add field to model
- Create new backend module
- Add React component
- Update database schema
- Fix a bug (TDD workflow)
- Add translations
Tasks Behavior
- Task creation and basic fields
- Status lifecycle and priority levels
- Due dates and Defer Until
- Subtasks and hierarchy
- File attachments
- Project assignment and tags
- Task completion and history
- Habit mode and tracking
- Task deletion and permissions
Recurring Tasks Behavior
- How recurring tasks work (non-technical rules)
- Completion behavior and patterns
- Virtual instances and display rules
- Parent-child relationships
- Editing and deletion behavior
Today Page Sections
- How Overdue, Planned, Suggested, and Completed sections work
- Task filtering and display rules
- Section priority and deduplication logic
- User settings and customization
- Defer Until and timezone handling
Upcoming View
- How the 7-day Upcoming view works
- Day-based grouping and organization
- Recurring task virtual occurrences
- Defer Until and status filtering
- Differences from Today view
Inbox Page
- Quick capture system for unorganized thoughts
- Smart parsing of hashtags, projects, and URLs
- Intelligent suggestions (Task vs Note vs Project)
- Converting inbox items to structured content
- Telegram integration and auto-refresh
- Keyboard shortcuts and workflows
Notes System
- Flexible information and reference storage
- Markdown support and rich text rendering
- Auto-save functionality (1-second debounce)
- Project linking and tag-based organization
- Focus mode for distraction-free writing
- Color customization for visual organization
- Integration with inbox and project workflows
Projects
- Project hierarchy and organization (Areas > Projects > Tasks)
- Status lifecycle and stalled detection
- Completion tracking and progress metrics
- Project sharing and collaboration permissions
- Due dates, notifications, and priorities
- Deletion behavior (orphaning vs cascading)
- Filtering, grouping, and sidebar pinning
Areas
- Top-level organizational categories for life domains
- Simple structure with name and description
- Optional containers for grouping projects
- Cascade behavior when deleting (orphans projects)
- Grid view with alphabetical sorting
- Integration with Projects page filtering and grouping
Views System
- Smart saved searches for tasks, notes, and projects
- Creating views from Universal Search
- Pinning and reordering views in sidebar
- Filtering, sorting, and grouping within views
- View management (rename, delete, pin/unpin)
- URL parameters and deep linking
- Pagination and performance
User Management
- Registration flow and email verification
- Authentication (session-based and API tokens)
- User roles and admin system
- Resource permissions and sharing
- Profile management and preferences
- Password and avatar management
- API token management
- Admin user CRUD operations
Tags System
- Cross-entity labeling and categorization (tasks, notes, projects)
- Auto-creation and validation rules
- Tag management (create, edit, delete, rename)
- Tag detail pages with filtering and search
- Alphabetical grouping and organization
- Hashtag parsing from inbox items
- Tag input component with autocomplete
Claude Memory & Preferences
- PR and commit message preferences
- Testing preferences
- Common patterns to remember
- Known issues and solutions

Project Overview

What This Project Does

Tududi is a self-hosted task management system designed around hierarchical organization and smart automation. It prioritizes user flow over rigid structures - a productivity tool that doesn't "fight back."

Core Philosophy:

Key Capabilities:

Hierarchical Organization: Areas > Projects > Tasks > Subtasks
Smart Recurring Tasks: Multiple patterns with parent-child tracking
Multi-Language Support: 24 languages via i18next
Collaboration: Project sharing with granular permissions
REST API: Swagger docs + personal API tokens
Telegram Integration: Create tasks via messages, daily digests
Tag System: Flexible tagging across tasks, notes, projects

Target Users: Self-hosting individuals and teams managing personal or collaborative productivity

Technology Stack

Frontend:

React 18 + TypeScript 5.6
Webpack 5 (build) + webpack-dev-server (development)
Tailwind CSS 3.4 + Heroicons
Zustand (global state) + SWR (server state)
React Router 6, i18next (24 languages)

Backend:

Express 4.21 + Sequelize 6.37 (ORM)
SQLite 5.1 (WAL mode, optimized)
bcrypt + express-session (auth)
Swagger (API docs), Multer (uploads)
node-cron (scheduling), Nodemailer (email)

Testing:

Jest (backend + frontend)
Playwright (E2E)
Supertest (API integration tests)

Critical Paths Quick Reference

Task	Location
Add backend feature	`/backend/modules/[feature]/`
Create model	`/backend/models/[model].js`
Database migration	`/backend/migrations/`
React component	`/frontend/components/[Feature]/`
API routes	`/backend/modules/[module]/routes.js`
Global state	`/frontend/store/useStore.ts`
API client	`/frontend/utils/[resource]Service.ts`

Document	Audience	Purpose
README.md	Users	Features, Docker setup, quick start
CONTRIBUTING.md	Contributors	PR workflow, code of conduct
docs.tududi.com	End users	Full user documentation
Swagger API docs	API consumers	API endpoints (after auth)
CLAUDE.md	Developers, AI	Codebase architecture, patterns

External Resources

Roadmap: GitHub Project
Community:
- Discord
- Reddit
- Issues
- Discussions

Document Version: 1.0.0 Last Updated: 2026-03-14 Maintainer: Update when architecture changes or patterns evolve

9.4 KiB Raw Blame History