Skip to main content

Inbox Page

This document explains how the Inbox page works in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/inbox/ and frontend components in /frontend/components/Inbox/.

Overview​

The Inbox is tududi's quick capture system - a temporary holding area where you can rapidly dump ideas, tasks, notes, and links without worrying about organization. It's designed to get things out of your head fast, then process them later into structured tasks, projects, or notes.

Key characteristics:

  • Zero friction capture - just type and submit
  • Smart parsing of hashtags, projects, and URLs
  • AI-powered suggestions for what to create
  • Convert items to tasks, notes, or projects
  • Integration with Telegram for remote capture

URL: /inbox

Core Principles​

  1. Capture first, organize later

    • Add items instantly without choosing status, priority, or due dates
    • Process and categorize items when you have time to think

  2. One place for everything

    • Tasks, notes, bookmarks, random thoughts - all start here
    • Sort them out later into appropriate places

  3. Smart automation helps

    • System detects patterns in your input
    • Suggests task vs. note vs. project based on content
    • Auto-extracts tags and project references

How to Add Items to Inbox​

Quick Capture Input​

Located at the top of the Inbox page:

  1. Type your content in the text field

    • Plain text: Remember to buy milk
    • With tags: Call dentist #health #urgent
    • With project: Review proposal +ClientProject #review
    • URLs: https://example.com/article
    • Mixed: Read this article https://example.com +Reading #bookmark

  2. Press Enter or Tab to submit (configurable in settings)

    • Item is saved to inbox immediately
    • Input clears, ready for next item
    • Can add multiple items rapidly

  3. Input auto-focuses when you navigate to /inbox

    • Keyboard shortcut: g then i (Go to Inbox)
    • Sidebar navigation clicks auto-focus input

Telegram Integration​

Send messages to your tududi bot:

  • Each message creates an inbox item
  • Source is marked as telegram
  • Appears in your inbox within ~15 seconds
  • You get a toast notification when new items arrive

Smart Parsing Rules​

The system automatically analyzes your input and extracts metadata:

1. Hashtags (Tags)​

Syntax: #tagname

Rules:

  • Must start with # followed by alphanumeric characters, hyphens, or underscores
  • Valid: #work, #high-priority, #q1_2026
  • Invalid: #with spaces, #emoji🎉, #punctuation!
  • Can appear anywhere in the text
  • Multiple tags supported: Task here #work #urgent #review

Grouping:

  • Consecutive tags/projects are treated as a group
  • Example: Buy groceries #food #shopping #weekly → extracts all 3 tags
  • Group must be contiguous (separated by spaces from other words)

Tag creation:

  • If tag doesn't exist, it's created when you convert to task/note/project
  • Tags are case-insensitive: #Work = #work = #WORK

2. Project References​

Syntax: +projectname or +"project with spaces"

Rules:

  • Must start with + followed by project name
  • No spaces: +HomeRenovation
  • With spaces: +"Home Renovation" (use quotes)
  • Valid: +work, +Q1Planning, +"Client Project"
  • Can appear anywhere in the text

Behavior:

  • If project exists, it's linked automatically
  • If project doesn't exist, you'll be prompted to create it
  • Only the first project reference is used when converting
  • Multiple references are parsed but only first is applied

3. URL Detection​

What counts as a URL:

  • Must start with http:// or https://
  • Example: https://example.com, http://blog.com/post

Special handling:

  • URLs automatically get #bookmark tag added
  • When converted to note, system tries to fetch page title
  • Title extraction has 3-second timeout
  • If title fetch fails, URL itself is used as title

Bookmark auto-tagging:

  • If you add #bookmark manually, it's preserved
  • If you don't, system adds it automatically for URLs
  • Applies to both explicit tags and when converting to note

4. Cleaned Content​

After parsing, the system creates "cleaned content":

  • Original: Review contract +ClientWork #urgent #review
  • Cleaned: Review contract
  • Tags and projects are stripped for display/conversion
  • Cleaned version is used as task name, note title, or project name

Intelligent Suggestions​

The system analyzes your content and suggests what type of item to create:

Suggestion Logic​

1. Suggests TASK when:

  • Content starts with an action verb (detected using NLP)
  • Has a project reference
  • Examples:
    • ✅ Call John +Work → Suggests Task (verb "Call")
    • ✅ Review proposal +ClientProject → Suggests Task (verb "Review")
    • ✅ Fix the bug +Development → Suggests Task (verb "Fix")

2. Suggests NOTE when:

  • Content is a URL (bookmark)
  • Has explicit #bookmark tag
  • Has a project reference but no action verb
  • Examples:
    • ✅ https://example.com/article +Reading → Suggests Note (URL)
    • ✅ Meeting notes from today +Project1 #bookmark → Suggests Note (bookmark tag)
    • ✅ Important info +Work → Suggests Note (no verb)

3. No suggestion when:

  • No project reference
  • Just plain text or tags without context
  • Examples:
    • ⚪ Random thought #idea → No suggestion
    • ⚪ Buy milk → No suggestion
    • ⚪ https://example.com → Shows URL icon, but no suggestion (no project)

Visual Indicators​

Suggestion badges:

  • Blue "Task" badge appears if suggested as task
  • Purple "Note" badge appears if suggested as note
  • Reason shown in tooltip: "verb detected", "bookmark tag", "URL detected"

Icons:

  • 🌐 Globe icon: Bookmark/URL content
  • 📄 Document icon: Plain text
  • 📝 Purple document: Long-form text (has title + content)

Converting Inbox Items​

Each inbox item can be converted to three types:

1. Convert to Task​

What happens:

  1. Opens the task detail page in edit mode
  2. Pre-fills task name with cleaned content
  3. Applies tags from hashtags
  4. Links to project if project reference found
  5. Status defaults to "Not Started"
  6. After saving, inbox item is marked as "processed"

Use cases:

  • Action items: Call dentist #health
  • Work tasks: Review PR #dev +ProjectX
  • Todos with deadlines: Submit report #work #urgent

Keyboard shortcut in quick capture:

  • Ctrl+T (Windows/Linux) or Cmd+T (Mac) to convert to task directly

2. Convert to Note​

What happens:

  1. Opens note modal
  2. Pre-fills note content with original text
  3. If URL: fetches page title and uses as note title (3s timeout)
  4. Applies tags from hashtags + #bookmark if URL
  5. Links to project if project reference found
  6. After saving, inbox item is marked as "processed"

Use cases:

  • Bookmarks: https://article.com +Reading
  • Ideas: New feature idea for app +Development
  • Reference material: Meeting notes from today +ClientProject

Keyboard shortcut in quick capture:

  • Ctrl+N (Windows/Linux) or Cmd+N (Mac) to convert to note directly

3. Convert to Project​

What happens:

  1. Opens project modal
  2. Pre-fills project name with cleaned content
  3. Applies tags from hashtags
  4. Status defaults to "Planned"
  5. After saving, inbox item is marked as "processed"

Use cases:

  • New initiatives: Website redesign #q1 #priority
  • Areas of work: Home renovation #personal
  • Client work: New client onboarding #clients

Keyboard shortcut in quick capture:

  • Ctrl+P (Windows/Linux) or Cmd+P (Mac) to convert to project directly

Direct Creation vs. Modal Editing​

For tasks: System immediately navigates to task detail page for editing

  • No modal - you edit inline on the task page
  • Gives you full access to all task fields
  • Back button returns to inbox

For notes and projects: Modal opens for editing

  • Edit within overlay modal
  • Save or cancel without leaving inbox page
  • More lightweight for quick additions

Inbox Item Lifecycle​

States​

  1. Added (status: added)

    • Freshly created item
    • Appears in inbox list
    • Awaiting processing

  2. Processed (status: processed)

    • Converted to task, note, or project
    • Removed from inbox view
    • Stored in database for history (not deleted)

Processing​

What "processing" means:

  • Marks item as processed
  • Removes from visible inbox
  • Preserves in database for audit trail
  • Cannot be un-processed (one-way action)

When items are auto-processed:

  • When you convert to task and save
  • When you convert to note and save
  • When you convert to project and save

Manual processing:

  • Not directly exposed in UI
  • Happens automatically on conversion
  • No "Mark as processed" button needed

Editing Inbox Items​

Inline Editing​

How to edit:

  1. Click anywhere on the inbox item text
  2. Item expands into editable composer
  3. Modify text, add/remove tags or projects
  4. Press Enter or click outside to save
  5. Press Esc to cancel changes

What you can edit:

  • Full content/text
  • Add or remove hashtags
  • Add or remove project references
  • URLs are preserved as text

Editing rules:

  • If content unchanged, no update is sent
  • Editing re-runs smart parsing
  • Suggestions update based on new content
  • Keyboard shortcuts (Ctrl+T, Ctrl+N, Ctrl+P) work while editing

While editing, you see action buttons:

  • Task button: Convert to task with current content
  • Note button: Convert to note with current content
  • Project button: Convert to project with current content
  • Delete button: Remove inbox item permanently

Deleting Inbox Items​

Confirmation​

Steps:

  1. Click Delete button in composer footer
  2. Confirmation dialog appears
  3. Confirm or cancel

What gets deleted:

  • Inbox item is permanently removed from database
  • NOT marked as processed - it's deleted
  • No undo option

When to delete vs. process​

Delete when:

  • Item is no longer relevant
  • Duplicate entry
  • Captured by mistake
  • Spam/noise

Process when:

  • Item becomes task/note/project
  • Actually converting to structured content
  • Want to preserve in audit trail

Pagination and Loading​

Initial Load​

  • Shows 20 items by default
  • Most recent items first (newest at top)
  • Loading screen while fetching

Load More​

When "Load More" button appears:

  • You have more than 20 items
  • Shows: "Showing X of Y items"
  • Button at bottom of list

How it works:

  1. Click "Load More" button
  2. Fetches next 20 items
  3. Appends to current list
  4. Updates count display
  5. Button disappears when all items loaded

URL state:

  • After loading more: URL updates to ?loaded=40 (or current count)
  • Bookmarking preserves loaded count
  • Refreshing page maintains loaded count from URL

No infinite scroll:

  • Manual "Load More" button only
  • Intentional - prevents accidental loading
  • Better performance for large inboxes

Auto-Refresh and Polling​

Background Polling​

How it works:

  • Every 15 seconds, checks for new items
  • Fetches updated inbox from server
  • Preserves current scroll position
  • Maintains loaded count (doesn't reset to 20)

What triggers updates:

  • Telegram messages arrive
  • Other devices add items
  • Web app open in multiple tabs

Notifications:

  • Toast notification when new Telegram item detected
  • Shows first item's content
  • If multiple items: shows count of additional items
  • Example: "New item from Telegram: Buy milk" + "2 more new items added"

Manual Refresh​

Keyboard shortcut:

  • r key: Force refresh inbox
  • Fetches latest items immediately
  • Useful if polling missed an update

When refresh happens automatically:

  • After you create an item via quick capture
  • After you delete an item
  • After you convert an item (it's removed)
  • Navigation to/from inbox page

Keyboard Shortcuts​

Global (anywhere in app)​

ShortcutAction
g then iGo to Inbox page

On Inbox page​

ShortcutAction
rRefresh inbox items
Focus in inputType to add item
Enter or TabSubmit item (configurable in settings)

In quick capture composer​

Shortcut (Win/Linux)Shortcut (Mac)Action
Ctrl+TCmd+TConvert to Task
Ctrl+NCmd+NConvert to Note
Ctrl+PCmd+PConvert to Project
Ctrl+EnterCmd+EnterSave to inbox instead of converting
EscEscCancel editing

While editing item​

ShortcutAction
EscCancel editing, revert changes
Click outsideSave changes
EnterSave changes (if not multiline)

Special Features​

1. Project Creation on the Fly​

When converting:

  • If you reference a project that doesn't exist: +NewProject
  • System prompts to create the project
  • Project created with name "NewProject", status "Planned"
  • Task/note is then linked to newly created project

Workflow:

  1. Add inbox item: Review docs +NewClientProject #urgent
  2. Click "Task" to convert
  3. System detects NewClientProject doesn't exist
  4. Project created automatically
  5. Task is linked to new project

2. Tag Creation on the Fly​

When converting:

  • If you use hashtag that doesn't exist: #newtag
  • Tag is created automatically during conversion
  • No confirmation needed
  • Tag appears in tag list immediately

Case insensitivity:

  • #Work, #work, #WORK all resolve to same tag
  • First occurrence determines the canonical case
  • Subsequent uses are normalized to existing tag

3. URL Title Extraction​

For bookmarks:

  • When converting URL to note
  • System fetches the webpage
  • Extracts <title> tag from HTML
  • Uses as note title
  • 3-second timeout - if it fails, uses URL as title

Example:

  • Input: https://example.com/article
  • System fetches page, finds title: "10 Tips for Productivity"
  • Note created with title: "10 Tips for Productivity"
  • Content: https://example.com/article
  • Tags: #bookmark (auto-added)

4. Multi-Source Capture​

Sources tracked:

  • web: Added via web interface (quick capture)
  • telegram: Added via Telegram bot
  • api: Added via REST API (rare)

Why it matters:

  • Can filter by source (not in UI, but in database)
  • Telegram items show notification on arrival
  • Useful for debugging integration issues

5. Long-Form Content​

Handling multi-line input:

  • Quick capture supports multi-line (Shift+Enter for new line)
  • First line becomes title
  • Full text stored as content
  • Title shown in inbox list
  • Content accessible when editing

Visual indicator:

  • Purple document icon for items with title+content
  • Gray document icon for plain text items
  • Globe icon for URLs/bookmarks

Display and Organization​

Sort Order​

Inbox items are always sorted by:

  • Creation date descending (newest first)
  • No other sort options available
  • Newest items at top encourages processing fresh captures

No Filtering​

Intentional limitation:

  • No search within inbox
  • No tag filtering
  • No project filtering
  • Philosophy: Inbox is temporary - process items, don't organize them here

No Grouping​

All items in flat list:

  • No grouping by date
  • No grouping by source
  • No grouping by tags/projects
  • Keeps it simple and fast to scan

Example Workflows​

Workflow 1: Quick Task Capture​

Scenario: You remember a task while working on something else

  1. Press g then i to open inbox
  2. Type: Email report to manager +Work #urgent
  3. Press Enter
  4. System suggests "Task" (verb detected)
  5. Click "Task" button or press Ctrl+T
  6. Task detail page opens with:
    • Name: "Email report to manager"
    • Project: Work
    • Tags: #urgent
  7. Set due date, priority, etc.
  8. Save task
  9. Inbox item auto-processed and removed

Workflow 2: Bookmark Collection​

Scenario: Found an interesting article to read later

  1. Navigate to /inbox
  2. Paste URL: https://medium.com/article +Reading
  3. Press Enter
  4. System shows globe icon (URL detected)
  5. Click "Note" button or press Ctrl+N
  6. System fetches article title: "How to Learn Faster"
  7. Note modal opens:
    • Title: "How to Learn Faster"
    • Content: https://medium.com/article
    • Project: Reading
    • Tags: #bookmark (auto-added)
  8. Save note
  9. Inbox item removed

Workflow 3: Telegram to Task​

Scenario: You're away from computer, send task to Telegram bot

  1. Send message to Telegram bot: Buy birthday gift for mom #personal #shopping
  2. Within 15 seconds, item appears in web inbox
  3. Toast notification: "New item from Telegram: Buy birthday gift for mom"
  4. Later, at computer, open /inbox
  5. See the item with tags parsed: #personal, #shopping
  6. Click to edit, add project: +PersonalLife
  7. Click "Task" to convert
  8. Set due date (her birthday)
  9. Save - task created, inbox cleared

Workflow 4: Batch Processing​

Scenario: Morning routine - clear out yesterday's inbox

  1. Open /inbox - see 8 items
  2. First item: Call plumber #home → Click "Task", set due today, save
  3. Second item: https://article.com +Reading → Click "Note", save
  4. Third item: Random idea for app → Edit, add +ProjectIdeas, click "Note"
  5. Fourth item: Buy milk → Delete (already done)
  6. Continue through all items
  7. Inbox empty - ready for new day

Workflow 5: Quick Project Ideation​

Scenario: Brainstorming new project ideas

  1. Press g then i
  2. Type rapid-fire ideas:
    • Redesign homepage #q2 #design
    • Build mobile app #q2 #dev
    • Customer research #q1 #research
  3. Later, convert each to projects:
    • Each becomes a project with tags
    • Start fleshing out project details
    • Add tasks to each project

Common Patterns​

Pattern: URL → Note with Bookmark Tag​

Input: https://example.com +Reading Result:

  • System detects URL
  • Auto-adds #bookmark tag
  • Suggests "Note"
  • Fetches page title
  • Creates note linked to Reading project

Pattern: Verb + Project → Task​

Input: Review proposal +ClientWork #urgent Result:

  • System detects verb "Review"
  • Suggests "Task"
  • Creates task:
    • Name: "Review proposal"
    • Project: ClientWork
    • Tags: #urgent

Pattern: No Project → No Suggestion​

Input: Random thought #idea Result:

  • No project reference
  • No suggestion shown
  • Can manually convert to task, note, or project
  • Tags are still parsed

Pattern: Multi-Tag Grouping​

Input: Task here #work #urgent #review and more text Result:

  • All consecutive tags extracted: work, urgent, review
  • Cleaned content: "Task here and more text"
  • Tags group is contiguous at end of thought

Troubleshooting​

"My tags aren't being detected"​

Check:

  1. Are tags alphanumeric + hyphens/underscores only?
    • ❌ #tag with spaces
    • ✅ #tag-with-hyphens
  2. Are tags separated by spaces from words?
    • ❌ word#tag
    • ✅ word #tag

"My project reference isn't working"​

Check:

  1. Did you use + prefix?
    • ❌ Project Name
    • ✅ +ProjectName
  2. Does project name have spaces? Use quotes:
    • ❌ +Client Project
    • ✅ +"Client Project"
  3. Does the project exist? System links only to existing projects

"Inbox item didn't get processed after conversion"​

Possible causes:

  • Conversion failed (check for error toast)
  • Network error during save
  • Item still showing because page didn't refresh
  • Try manual refresh with r key

"Telegram items not appearing"​

Check:

  1. Is Telegram bot properly configured? (Settings > Telegram)
  2. Wait up to 15 seconds for polling cycle
  3. Check inbox for toast notification
  4. Try manual refresh with r key
  5. Verify bot token is correct in settings

"URL title extraction failed"​

Why it happens:

  • Website blocks scraping/bots
  • Website requires JavaScript to load
  • Network timeout (3 seconds)
  • Invalid URL format

What to do:

  • System falls back to using URL as title
  • You can manually edit title in note modal
  • URL content is still saved correctly

Technical Implementation Files:

  • Inbox processing service: /backend/modules/inbox/inboxProcessingService.js
  • Inbox model: /backend/models/inbox_item.js
  • Inbox API routes: /backend/modules/inbox/routes.js
  • Inbox controller: /backend/modules/inbox/controller.js
  • Frontend components: /frontend/components/Inbox/
  • Quick capture input: /frontend/components/Inbox/QuickCaptureInput.tsx
  • Item detail: /frontend/components/Inbox/InboxItemDetail.tsx
  • Inbox service: /frontend/utils/inboxService.ts

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