Skip to content

INBOX_VISION.md

Latest commit

 

History

History
99 lines (79 loc) · 3.83 KB

INBOX_VISION.md

File metadata and controls

99 lines (79 loc) · 3.83 KB

Universal Inbox Vision

Core Philosophy

The inbox is the most critical entry point in any GTD system. Our goal is to make capturing thoughts so effortless that the friction of recording an idea is never a barrier. The unreachable ideal: any way a user might want to add items already exists.

Guiding Principles

1. Capture First, Categorize Later

The inbox exists to get things out of your head quickly. Don't add friction at capture time - that's what processing is for.

2. Meet Users Where They Are

People have different workflows, devices, and contexts. Support capture from:

  • The web UI (current)
  • Mobile devices
  • Email forwarding
  • Browser extensions
  • CLI tools
  • Voice assistants
  • API integrations
  • Watched folders/files
  • Messaging platforms (Slack, Discord, Teams)
  • Calendar events
  • Note-taking apps
  • And sources we haven't imagined yet

3. Preserve Context

When capturing from external sources, preserve useful metadata:

  • Source/origin of the item
  • Timestamp of original creation
  • Links back to source material
  • Any attachments or related content

4. Graceful Degradation

If rich capture isn't possible, simple text capture is always better than nothing.

Architectural Guidance

Stay Flexible - Learn From Experience

We don't yet know what patterns will emerge across different integrations. Resist the urge to over-architect upfront:

  • Start concrete: Build the first few integrations as straightforward implementations
  • Find patterns: Let common abstractions emerge from real code, not speculation
  • Refactor when clear: Extract shared patterns only when you've seen them repeat
  • Document learnings: Note what worked and what didn't for each integration

Potential Future Structure

As integrations grow, we may need:

  • A separate project or solution for "Inbox Connectors"
  • A plugin/extension architecture
  • Shared contracts/interfaces for inbox submission
  • Background processing for async sources

But don't build this infrastructure until we need it. The first 2-3 integrations should inform the architecture, not the other way around.

Current Integration Point

For now, all inbox capture flows through IInboxService.CreateAsync(). This is intentionally simple. As we add integrations, we'll learn whether we need:

  • Batch operations
  • Async/queued processing
  • Source-specific metadata
  • Deduplication logic
  • Rate limiting

Integration Ideas (Unprioritized)

Potential capture sources to explore:

  • REST API endpoint for external tools
  • Email-to-inbox (unique email address per user)
  • Browser extension (capture current page/selection)
  • Mobile app / PWA
  • CLI tool (gtd add "remember to...")
  • File watcher (drop files in a folder)
  • IFTTT/Zapier webhooks
  • Telegram/Discord bot
  • Voice capture (speech-to-text)
  • Calendar integration (create inbox item from event)
  • Slack/Teams integration
  • Obsidian/Notion sync

When Adding a New Integration

  1. Keep it simple - Get something working end-to-end first
  2. Don't abstract prematurely - Duplication is cheaper than wrong abstraction
  3. Preserve source info - Store where the item came from
  4. Handle failures gracefully - Users should know if capture failed
  5. Document the integration - How to set it up, limitations, etc.
  6. Write tests - Integration points are critical paths
  7. Note patterns - After completing, note any patterns that could be shared

Questions to Answer Through Experience

  • Should connectors live in the main project or separate?
  • Do we need a message queue for async sources?
  • How do we handle authentication for external services?
  • What metadata schema works across sources?
  • How do we handle duplicate detection?
  • Should integrations be user-configurable?

These questions are intentionally unanswered - we'll learn the right answers by building.