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​

Share Levels​

  1. Read-Only (ro)

    • View project, tasks, and notes
    • Cannot edit or add content
    • Cannot share with others

  2. Read-Write (rw)

    • View project, tasks, and notes
    • Edit existing content
    • Add new tasks and notes
    • Cannot delete project
    • Cannot change sharing settings

  3. Owner (implicit)

    • Full control
    • Can delete project
    • Can change sharing settings
    • Can change project status

Sharing a Project​

How to share:

  1. Open project detail page
  2. Click "Share" button
  3. Enter email of user to share with
  4. Select access level (read-only or read-write)
  5. User receives notification

Requirements:

  • Other user must have a tududi account
  • Must use exact email address
  • Cannot share with yourself

Access Inheritance​

When you share a project:

  • Shared user gets access to ALL tasks in project
  • Shared user gets access to ALL notes in project
  • Access level applies to entire project tree

Example:

  • You share "Website Redesign" project with Alice (read-write)
  • Alice can now view/edit:
    • The project itself
    • All tasks in the project
    • All notes in the project
    • All subtasks of tasks in the project

Shared Projects Behavior​

For shared users:

  • Shared projects appear in their Projects list
  • Can filter projects by ownership vs shared
  • Shared indicator shown on project card
  • Cannot change Area (only owner can)
  • Cannot delete project (only owner can)

Notifications:

  • Project owner sees share count badge
  • Shared users see owner's name
  • Activity on shared project can trigger notifications

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