tududi Documentation

The Notes system is a flexible capture and reference tool for storing information, ideas, bookmarks, and meeting notes. Unlike tasks, notes are purely informational and do not have due dates, priorities, or completion states.

Key Features:

• Rich Text: Full Markdown support (GitHub-flavored).
• Organization: Optional project association and tag-based categorization.
• Auto-save: Automatically saves changes every 1 second.
• Customization: 10 predefined background colors for visual organization.
• Focus Mode: A distraction-free, full-screen editing mode.
• Search: Real-time search across both titles and content.

Access URLs:

• List view: /notes
• Individual note: /notes/:uid

The tududi Today page organizes tasks into four main sections. Each task is assigned to exactly one section based on a specific priority hierarchy to prevent duplication:

1. Completed: Tasks finished within the current 24-hour window (highest priority).
2. Planned: Tasks with statuses In Progress, Planned, or Waiting.
3. Overdue: Tasks with a due date before today that are not already in the Planned section.
4. Suggested: Tasks that meet eligibility criteria and are not visible in any of the above sections (lowest priority).

Section Priority Logic Examples:

• An overdue task marked as In Progress will appear in Planned, not Overdue.
• A high-priority task with no due date and Not Started status will appear in Suggested, not Overdue.
• A task deferred to a future date will be hidden from all sections until the defer time passes.

In tududi, a recurring task is a single task that automatically resets itself upon completion. Instead of creating new task copies, the system uses In-Place Advancement: the same task ID, title, and details are reused, but the due date is updated based on the recurrence pattern.

Key behaviors include:

• Virtual Instances: Future occurrences are displayed as previews in task lists but do not exist as separate database records until the current occurrence is completed.
• Completion History: While the task advances in place, all past completions are preserved in a separate recurring_completions table.
• Overdue Handling: If a task becomes overdue, the system does not pile up multiple occurrences; it shows only the current/next occurrence and automatically skips past-due instances.

The frontend is a React application organized by feature and responsibility. Key architectural layers include:

• Entry & Routing: index.tsx handles initialization (i18n, dark mode, service workers), while App.tsx manages routes and authentication.
• State Management: Global state (tasks, projects, UI state) is managed via Zustand in store/useStore.ts. React Contexts are used for specific concerns like ModalContext.tsx and SidebarContext.tsx.
• Components: Organized by feature (e.g., components/Task/, components/Project/) with a Shared/ directory for reusable UI elements like Modals and Form inputs.
• Data Fetching & API: API clients are located in utils/ (e.g., tasksService.ts, projectsService.ts).
• Type Definitions: TypeScript interfaces for all core entities (Task, Project, User, etc.) are located in entities/.

tududi uses a modern full-stack architecture:

Frontend

• Framework: React 18.3.1 with TypeScript 5.6.2
• State Management: Zustand (global state) and SWR (server state)
• Styling: Tailwind CSS 3.4.13
• Routing: React Router DOM 6.26.2
• Drag & Drop: @dnd-kit

Backend

• Framework: Express.js 4.21.2
• ORM: Sequelize 6.37.7
• Database: SQLite 5.1.7 (optimized with WAL mode and memory-mapped I/O)
• Authentication: bcrypt, express-session, and connect-session-sequelize
• Scheduling: node-cron 4.1.0

Testing

• Backend: Jest and Supertest
• Frontend: Jest and React Testing Library
• E2E: Playwright

In tududi, Projects act as mid-level containers for organizing work, sitting between Areas (high-level life domains) and Tasks/Notes (actionable items or reference material).

Core Principles

• Optional Containers: Tasks and notes can exist without a project (orphaned).
• No Cascade Delete for Notes: Deleting a project orphans its notes (sets project_id to null) rather than deleting them, preventing data loss.
• Automatic Progress Tracking: Completion percentages and "stalled" status are calculated automatically based on child tasks.
• Sharing: Projects can be shared with other users (read-only or read-write), and access extends to all contained tasks and notes.

Hierarchy Example

• Area: Personal
  • Project: Home Renovation
    • Task: Get quotes from contractors
    • Note: Inspiration photos from Pinterest

The project is organized as a monorepo. The root directory contains configuration files for the entire project, deployment assets, and the main source directories for the backend and frontend.

/tududi/
├── backend/               # Express backend
├── frontend/              # React frontend
├── public/               # Static assets (Service Worker, PWA manifest, i18n)
├── e2e/                   # Playwright E2E tests
├── scripts/               # Build and utility scripts
├── dist/                  # Production build output
└── package.json           # Root scripts and dependencies

tududi uses a hierarchical structure to organize information, with Areas serving as the highest level of organization. Areas represent broad life domains (e.g., Work, Personal, Health) and contain Goals and Projects.

Hierarchy Structure:

• Areas (Life domains)
  • Goals (Season/year-scale outcomes)
    • Projects (Specific initiatives)
      • Tasks (Actionable items)
        • Subtasks

Note: Projects can exist without being assigned to an Area.

Tududi includes optional intelligence features to assist with productivity. These can be enabled or disabled.

Features:

• Auto-suggest next actions: Suggests actions based on task context.
• Smart suggestions: Populates the "Suggested" section on the Today page.
• Productivity insights: Provides patterns and insights.
• Next task recommendation: Recommends tasks based on priority, due date, and context.

Algorithm Factors: Suggestions are ranked based on due dates, priority levels, project deadlines, task age, and user completion patterns (e.g., time of day worked).

End-to-end tests are implemented using Playwright.

• Test Specs: Located in e2e/tests/ (e.g., login.spec.ts, tasks.spec.ts).
• Test Runner: Use the script located at e2e/bin/run-e2e.sh to execute tests.

The Upcoming view (accessible at /upcoming) is a forward-looking calendar showing tasks scheduled for the next 7 days, organized by date.

Key Characteristics:

• Time Range: Starts today at midnight and ends 7 days from now at 11:59 PM.
• Organization: Grouped by day (e.g., "Today", "Tomorrow", "Monday, March 17") rather than by status or project. Tasks without due dates appear in a "No Due Date" section.
• Recurring Tasks: Displays "virtual occurrences" generated on-the-fly based on recurrence patterns.
• Limitations: You cannot create new tasks directly from this view. Use the Inbox, Today view, or specific projects to create tasks. Search is also disabled in this view.
• Layout: Uses a horizontal board-style layout on desktop and a vertical stacked layout on mobile.