Skip to main content

Projects

This document explains how projects work in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/projects/ and frontend components in /frontend/components/Project/.

Overview​

Projects are containers for organizing related tasks and notes in tududi. They sit in the middle of the hierarchy (Areas > Projects > Tasks) and provide a focused workspace for achieving specific goals.

Key characteristics:

  • Group related tasks and notes together
  • Track progress and completion percentage
  • Can belong to an Area for higher-level organization
  • Support collaboration through sharing
  • Have status lifecycle (Planned → In Progress → Done)
  • Can be pinned to sidebar for quick access
  • Support tags, priorities, and due dates

URL: /project/:uid

Core Principles​

  1. Projects are optional containers

    • Tasks and notes can exist without projects (orphaned)
    • But projects help organize work into logical groupings

  2. Projects don't cascade delete

    • Deleting a project orphans its tasks/notes, doesn't delete them
    • This prevents accidental data loss

  3. Projects track progress automatically

    • Completion percentage calculated from child tasks
    • "Stalled" detection for projects with no active tasks

  4. Projects can be shared

    • Share with other users (read-only or read-write)
    • Shared project access extends to all tasks/notes within

Hierarchy​

Areas (highest level - life domains)
  └── Projects (mid level - specific goals/initiatives)
        ├── Tasks (actionable items)
        └── Notes (reference material)

Example:

Area: "Personal"
  └── Project: "Home Renovation"
        ├── Task: "Get quotes from contractors"
        ├── Task: "Choose paint colors"
        └── Note: "Inspiration photos from Pinterest"

Project Properties​

Basic Information​

  1. Name (required)

    • The project title
    • Example: "Q1 Marketing Campaign", "Home Renovation", "Learn Spanish"

  2. Description (optional)

    • Longer explanation of the project's purpose
    • Supports multi-line text
    • Displayed at top of project page

  3. UID (auto-generated)

    • Unique identifier for the project
    • Used in URLs: /project/:uid
    • Cannot be changed

Organization​

  1. Area (optional)

    • Parent area this project belongs to
    • Used for high-level grouping
    • Can be changed or removed
    • Examples: "Work", "Personal", "Health"

  2. Tags (optional)

    • Flexible categorization system
    • Multiple tags supported: #q1, #urgent, #client-work
    • Tags created automatically when used
    • Shared across projects, tasks, and notes

Status and Lifecycle​

  1. Status (required, default: not_started)

    • Planned: Future project, not started yet
    • Not Started: Ready to begin but not yet started
    • In Progress: Currently being worked on
    • Waiting: Blocked or waiting on external dependency
    • Done: Project completed successfully
    • Cancelled: Project abandoned or no longer relevant

  2. Priority (optional)

    • 0 = None (default)
    • 1 = Medium
    • 2 = High
    • Visual indicator in UI (colored dot)

  3. Due Date (optional)

    • When the project should be completed
    • Triggers notifications when approaching or overdue
    • Displayed in project cards and detail view

Display and Organization​

  1. Pin to Sidebar (boolean, default: false)

    • Pins project to left sidebar for quick access
    • Pinned projects shown above unpinned ones
    • Useful for currently active projects

  2. Banner Image (optional)

    • Visual header image for the project
    • Uploaded via image picker
    • Displayed at top of project detail page
    • Can be edited or removed

Task Display Preferences​

  1. Show Completed Tasks (boolean, default: false)

    • Controls whether completed tasks are visible
    • Per-project setting
    • Helps reduce clutter on active projects

  2. Task Sort Order (string, default: created_at:desc)

    • How tasks are sorted within the project
    • Options: created_at:asc, created_at:desc, due_date:asc, priority:desc, etc.
    • Per-project preference

Calculated Properties​

These properties are computed automatically based on project content:

Task Status Tracking​

task_status object:

  • total: Total number of tasks in project
  • done: Count of completed tasks
  • in_progress: Count of tasks currently being worked on
  • not_started: Count of tasks not yet started

Example:

{
  "total": 10,
  "done": 6,
  "in_progress": 3,
  "not_started": 1
}

Completion Percentage​

completion_percentage: 0-100

  • Calculated as: (done / total) * 100
  • Rounded to whole number
  • Shows 0% if project has no tasks
  • Based on parent tasks only (subtasks don't count separately)

Stalled Detection​

is_stalled: true | false

  • A project is "stalled" when:
    • Status is in_progress OR planned
    • AND has zero active tasks (no "in_progress" or "not_started" tasks)
  • Indicates projects that need attention
  • Surfaced in Productivity Assistant

Example scenarios:

  • ✅ Status: in_progress, Tasks: 5 (3 done, 2 not_started) → NOT stalled
  • ❌ Status: in_progress, Tasks: 5 (all done) → STALLED
  • ✅ Status: done, Tasks: 5 (all done) → NOT stalled (done projects can't be stalled)
  • ❌ Status: planned, Tasks: 0 → STALLED

Sharing Metadata​

share_count: Number of users project is shared with is_shared: true if share_count > 0

Project Lifecycle​

Creating a Project​

Ways to create:

  1. Click "New Project" button on Projects page
  2. Use +Project syntax in Inbox and convert
  3. Create via modal when adding task/note

Required fields:

  • Name

Default values:

  • Status: not_started
  • Pin to sidebar: false
  • Show completed tasks: false
  • Task sort order: created_at:desc

Auto-generated:

  • UID (unique identifier)
  • Timestamps (created_at, updated_at)

Editing a Project​

What you can edit:

  • All basic properties (name, description, area, status, priority, due date)
  • Tags (add/remove)
  • Banner image (upload/change/remove)
  • Display preferences (pin, show completed, sort order)

What you cannot edit:

  • UID
  • User ID (owner)
  • Created timestamp

Who can edit:

  • Project owner (full access)
  • Users with read-write (rw) share access
  • Admin users

Changing Status​

Status transitions:

  • Any status can change to any other status (no enforced workflow)
  • Common flows:
    • planned → in_progress → done
    • not_started → in_progress → done
    • in_progress → waiting → in_progress
    • in_progress → cancelled

Effects of status change:

  • Affects "active projects" filter (planned/in_progress/waiting)
  • Affects stalled detection
  • Updates last modified timestamp

Deleting a Project​

What happens:

  1. Project record is deleted from database
  2. Tasks belonging to project are orphaned (project_id set to null)
  3. Notes belonging to project are orphaned (project_id set to null)
  4. Project tags associations are removed
  5. Share permissions are deleted

What is NOT deleted:

  • Tasks (they become orphaned, appear in "No Project" filter)
  • Notes (they become orphaned)
  • Tags (they remain in system)
  • Area (parent area is unaffected)

Who can delete:

  • Project owner only
  • Admin users

No undo:

  • Deletion is permanent
  • Use status cancelled if you want to preserve but deactivate

Areas and Projects​

What is an Area?​

An Area is a top-level category representing a life domain or responsibility area. Examples:

  • Personal
  • Work
  • Health
  • Finance
  • Learning

Relationship​

Projects belong to Areas (optional):

  • One project can belong to one area
  • A project can have no area (orphaned)
  • An area can have multiple projects
  • Deleting an area orphans its projects (doesn't delete them)

Grouping​

On Projects page:

  • Projects can be grouped by area (?grouped=true)
  • Shows "No Area" group for orphaned projects
  • Useful for high-level overview of work

Example grouped view:

Work
  ├── Q1 Marketing Campaign
  ├── Website Redesign
  └── Client Onboarding

Personal
  ├── Home Renovation
  └── Learn Spanish

No Area
  └── Random Ideas

Tasks and Notes in Projects​

Adding Tasks to Projects​

Ways to assign task to project:

  1. Select project in task detail modal
  2. Use +ProjectName syntax in Inbox
  3. Create task directly from project page
  4. Bulk assign existing orphaned tasks

Task inheritance:

  • Tasks inherit nothing from parent project
  • Task status is independent of project status
  • Task due date is independent of project due date
  • Task priority is independent of project priority

Task visibility:

  • All project tasks shown on project detail page
  • Can filter by status (not_started, in_progress, done)
  • Can toggle "Show completed" per project
  • Parent tasks only (subtasks nested under parents)

Adding Notes to Projects​

Ways to assign note to project:

  1. Select project in note modal
  2. Use +ProjectName syntax in Inbox when converting to note
  3. Create note directly from project page

Note display:

  • Notes shown in separate "Notes" section on project page
  • Sorted by most recent first
  • Can be tagged independently

Orphaned Tasks/Notes​

What are orphaned items:

  • Tasks or notes with no project assigned (project_id = null)
  • Created without project, or project was deleted

How to find:

  • Tasks page: Filter by "No Project"
  • Can bulk-assign to projects later

Not a problem:

  • Orphaned items are perfectly valid
  • Projects are optional organizational containers

Project Sharing and Collaboration​

Projects can be shared with other tududi accounts at read-only or read-write access, with access inherited by every task and note inside the project. See Project Sharing for the full walkthrough, share levels, and what collaborators can and can't do.

Due Dates and Notifications​

Setting Due Dates​

Project due date:

  • Optional field
  • Date + time picker
  • Represents project deadline

Independent from task due dates:

  • Project due date doesn't affect task due dates
  • Tasks can be due before, during, or after project due date
  • No validation or warnings if dates mismatch

Due Date Notifications​

Automated notifications created when:

  1. Due Soon: Project due date within 24 hours
  2. Overdue: Project due date has passed

Notification timing:

  • Checked via cron job (runs periodically)
  • Notifications sent in-app
  • Can also send via Telegram if configured

Notification rules:

  • Only for projects with status NOT done or cancelled
  • Only if user has notifications enabled for this type
  • Won't create duplicate notifications
  • Old unread notifications deleted before creating new one
  • Dismissed notifications won't be recreated

Example messages:

  • "Your project 'Website Redesign' is due in 6 hours"
  • "Your project 'Q1 Report' was due yesterday"
  • "Your project 'Client Onboarding' was due 3 days ago"

Filtering and Viewing Projects​

Projects List Page​

URL: /projects

Default view:

  • All projects for current user
  • Includes owned and shared projects
  • Sorted alphabetically by name
  • Shows project cards with:
    • Name, description (truncated)
    • Status badge
    • Priority indicator
    • Completion percentage
    • Task count
    • Tags
    • Area name
    • Pinned indicator
    • Shared indicator

Filter Options​

  1. By Status

    • Query: ?status=in_progress
    • Values: planned, not_started, in_progress, waiting, done, cancelled
    • Can filter multiple: ?status[]=in_progress&status[]=planned

  2. By Active State

    • Query: ?active=true
    • true: Shows planned, in_progress, waiting
    • false: Shows not_started, done, cancelled

  3. By Area

    • Query: ?area=:area-uid
    • Shows only projects in specified area
    • Use area UID from URL

  4. By Pinned

    • Query: ?pin_to_sidebar=true
    • true: Only pinned projects
    • false: Only unpinned projects

  5. Grouped by Area

    • Query: ?grouped=true
    • Groups projects under area names
    • Special "No Area" group for orphaned projects

Example URLs:

  • /projects?status=in_progress - Active projects
  • /projects?active=true - All active projects
  • /projects?pin_to_sidebar=true - Pinned projects only
  • /projects?area=abc123&grouped=true - Projects in specific area, grouped

What is Pinning?​

Pin to Sidebar is a quick-access feature that:

  • Shows project in left sidebar navigation
  • Provides one-click access to frequently used projects
  • Appears under "Pinned Projects" section

How to Pin​

Ways to pin:

  1. Click pin icon on project card
  2. Toggle "Pin to sidebar" in project modal
  3. Update via project detail page

Pin behavior:

  • Pinned projects shown above unpinned ones in sidebar
  • Sorted alphabetically within pinned section
  • Can pin unlimited projects (but UI gets crowded)

When to Pin​

Good candidates for pinning:

  • Currently active projects you access daily
  • Projects in "in_progress" status
  • Projects with frequent task additions
  • Projects you're actively collaborating on

Not recommended:

  • Completed or cancelled projects
  • Future/planned projects not yet active
  • Projects you rarely access

Project Insights and Metrics​

Task Status Metrics​

Displayed on project cards and detail page:

Total tasks: Count of all parent tasks (excluding subtasks) Completion percentage: Visual progress bar Breakdown by status:

  • Done (green)
  • In progress (blue)
  • Not started (gray)

Stalled Projects​

What is a stalled project?

  • Status is planned or in_progress
  • Has zero active tasks (all tasks are done, or no tasks exist)

Why it matters:

  • Indicates project needs attention
  • Either needs new tasks, or should change status to "done"
  • Surfaced in Productivity Assistant feature

How to fix:

  1. Add new tasks to move project forward
  2. Change status to "done" if actually complete
  3. Change status to "waiting" or "cancelled" if appropriate

Productivity Assistant​

Location: Today page (if enabled in settings)

Insights about projects:

  • Stalled Projects: Lists projects that need tasks/actions
  • Projects Near Deadline: Due soon or overdue
  • Vague Projects: Projects with vague task descriptions

Common Workflows​

Workflow 1: Start a New Project​

Scenario: Beginning a new initiative

  1. Navigate to /projects
  2. Click "New Project" button
  3. Fill in details:
    • Name: "Website Redesign"
    • Description: "Redesign company website for Q1 launch"
    • Area: Work
    • Status: Planned
    • Priority: High
    • Tags: #q1, #design
  4. Save project
  5. Add first task: "Research design trends"
  6. Change status to "In Progress" when ready to begin

Workflow 2: Track Project Progress​

Scenario: Monitoring ongoing project

  1. Open project detail page
  2. Review completion percentage (e.g., 60%)
  3. Check task breakdown:
    • 6 done
    • 2 in progress
    • 2 not started
  4. Complete some tasks
  5. Completion percentage updates automatically
  6. When all tasks done, mark project status as "Done"

Workflow 3: Share Project with Collaborator​

Scenario: Working with team member

  1. Open project "Client Onboarding"
  2. Click "Share" button
  3. Enter collaborator email: alice@example.com
  4. Select "Read-Write" access
  5. Save
  6. Alice receives notification
  7. Alice can now:
    • View all project tasks
    • Add new tasks
    • Complete tasks
    • Add notes
  8. Both see real-time updates

Workflow 4: Organize with Areas​

Scenario: High-level life organization

  1. Create Areas:
    • Work
    • Personal
    • Health
  2. Assign projects to areas:
    • "Q1 Marketing" → Work
    • "Home Renovation" → Personal
    • "Exercise Routine" → Health
  3. View projects grouped by area
  4. Get high-level view of balance across life domains

Workflow 5: Clean Up Completed Projects​

Scenario: End of quarter cleanup

  1. Navigate to /projects?status=in_progress
  2. Review each project:
    • If all tasks done → Change status to "Done"
    • If abandoned → Change status to "Cancelled"
    • If stalled → Add new tasks or change status
  3. Move completed projects out of active view
  4. Focus on truly active projects

Project Display Rules​

Project Cards (List View)​

Information shown:

  • Project name (bold, clickable)
  • Description (first 100 chars, truncated with "...")
  • Status badge (color-coded)
  • Priority dot (if set)
  • Completion percentage bar
  • Task count: "X of Y tasks done"
  • Area name (if assigned)
  • Tags (up to 3 shown, "+N more" if exceeded)
  • Last updated timestamp
  • Pin indicator (star icon)
  • Share indicator (user icon + count)

Color coding:

  • Planned: Purple badge
  • Not Started: Gray badge
  • In Progress: Blue badge
  • Waiting: Yellow badge
  • Done: Green badge
  • Cancelled: Red badge

Project Detail Page​

Sections:

  1. Banner Image (if set) - full-width header
  2. Project Header
    • Name (editable inline)
    • Status dropdown
    • Priority selector
    • Pin toggle
    • Share button
  3. Metadata Row
    • Area (linked)
    • Due date (if set)
    • Tags (editable)
  4. Description (expandable text area)
  5. Progress Section
    • Completion percentage bar
    • Task breakdown (done/in progress/not started)
  6. Tasks Section
    • Task list (sorted per project preference)
    • "Add Task" button
    • Show/hide completed toggle
  7. Notes Section
    • Note cards (most recent first)
    • "Add Note" button
  8. Insights Panel (if productivity assistant enabled)
    • Auto-suggested next actions
    • Stalled warning
    • Due date alerts

Special Features​

1. Auto-Suggest Next Action​

What it does:

  • AI-powered suggestions for next steps
  • Analyzes project context, tasks, and notes
  • Suggests concrete actions to move project forward

Appears when:

  • Project has description and some tasks
  • User has AI features enabled
  • Accessed via "Suggest Next Action" button

Example suggestions:

  • "Schedule a meeting with the designer"
  • "Review the latest mockups"
  • "Get feedback from stakeholders"

2. Banner Images​

Purpose:

  • Visual identity for projects
  • Makes projects more recognizable
  • Improves aesthetic appeal

How to set:

  1. Click "Edit Banner" on project detail page
  2. Upload image file (JPG, PNG)
  3. Image stored in /api/uploads/projects/
  4. Can replace or remove later

Recommended:

  • Use relevant imagery (website screenshot for web project, house for renovation)
  • High resolution (1200x400 or larger)
  • Landscape orientation

3. Task Sorting Preferences​

Per-project sorting:

  • Each project can have its own task sort order
  • Doesn't affect other projects
  • Persisted across sessions

Sort options:

  • Created date (newest/oldest first)
  • Due date (soonest/latest first)
  • Priority (highest/lowest first)
  • Status (by progress)
  • Name (A-Z, Z-A)

Use cases:

  • Sprint project: Sort by priority
  • Research project: Sort by created date
  • Deadline-driven project: Sort by due date

4. Keyboard Shortcuts​

On project page:

  • n: Create new task
  • Shift+N: Create new note
  • e: Edit project details
  • p: Pin/unpin project
  • /: Focus search

Global shortcuts:

  • g then p: Go to Projects page

Troubleshooting​

"My tasks disappeared when I deleted the project"​

What happened:

  • Tasks are not deleted, they're orphaned
  • They still exist in your database

How to find:

  1. Go to Tasks page
  2. Filter by "No Project"
  3. You'll see all orphaned tasks
  4. Re-assign to a different project if needed

"Project shows 0% complete but I have completed tasks"​

Possible causes:

  1. All completed items are subtasks (only parent tasks count)
  2. Completed items were soft-deleted
  3. Tasks belong to different project

How to check:

  1. Open project detail page
  2. Check task list - are completed tasks visible?
  3. Toggle "Show completed tasks" if hidden
  4. Verify tasks actually belong to this project

"Shared project not appearing for collaborator"​

Checklist:

  1. Did you use exact email address?
  2. Does user have tududi account with that email?
  3. Check share count - is it > 0?
  4. Have them refresh their projects list
  5. Check notifications - did they receive share notification?

"Project marked as stalled but it has tasks"​

Why it's stalled:

  • All tasks are marked "done"
  • Or all tasks are subtasks (parent tasks are all done)

How to fix:

  1. Add new tasks for next phase of work
  2. Or change project status to "done" if actually complete
  3. Or change status to "waiting" if blocked

"Can't delete a project"​

Possible reasons:

  1. You're not the owner (only owner can delete)
  2. Permission issue (check if you have rw or just ro)

Alternative:

  • If you can't delete, change status to "cancelled"
  • Unpin from sidebar
  • Filter it out of active views

Technical Implementation Files:

  • Project model: /backend/models/project.js
  • Area model: /backend/models/area.js
  • Projects service: /backend/modules/projects/service.js
  • Projects controller: /backend/modules/projects/controller.js
  • Projects repository: /backend/modules/projects/repository.js
  • Due project service: /backend/modules/projects/dueProjectService.js
  • Permissions service: /backend/services/permissionsService.js
  • Frontend components: /frontend/components/Project/
  • Project detail page: /frontend/components/Project/ProjectDetails.tsx
  • Project item card: /frontend/components/Project/ProjectItem.tsx
  • Project modal: /frontend/components/Project/ProjectModal.tsx
  • Share modal: /frontend/components/Project/ProjectShareModal.tsx

Document Version: 1.0.0 Last Updated: 2026-03-14 Audience: Developers, AI assistants, and end users