MagnumOpus/docs/plans/2026-03-10-magnum-opus-design.md

Magnum Opus — Design Document

Core Concept

A unified productivity system built on standard protocols (IMAP/SMTP, CalDAV, CardDAV). Email, tasks, calendar, and contacts share a single threaded interface. Everything that enters the system must be processed (inbox zero). The email thread is the fundamental unit — projects are just bigger threads.

Build for ourselves first, but with clean abstractions to make it a product later.

Inspirations

• macOS Mail (UI feel, three-column layout)
• Thunderbird (protocol breadth)
• OmniFocus (GTD task management depth)
• GTD / Inbox Zero (methodology)
• Emacs org-mode (file-based power — but too inaccessible)

Key Principles

• Standard protocols — IMAP/SMTP for email, CalDAV for tasks/calendar, CardDAV for contacts. Opening the same accounts in Apple Mail or Thunderbird shows normal, unmodified data.
• Unix philosophy — compose existing tools (mbsync, vdirsyncer, notmuch), don't reimplement them.
• Files are the source of truth — Maildir, VTODO, VEVENT, vCard. Syncable with any service. Theoretically usable from the CLI.
• Append-only history — nothing is deleted, ever. State changes are recorded like accounting entries. Export-and-compact is the only way to drop history (per-project or globally, e.g., yearly).
• Progressive disclosure — simple by default, structured on demand. Complexity surfaces only when the user needs it.
• Meet users where they are — familiar GUI, standard workflows. No new paradigms to learn.

---

Architecture

Backend (Uberspace)

Hono/Node API layer orchestrating unix tools:

• mbsync → IMAP sync to Maildir
• vdirsyncer → CalDAV/CardDAV sync to local files
• SQLite as a derived cache (rebuildable from files at any time)
• REST API for mutations, SSE (Server-Sent Events) for real-time push to clients

The backend is a thin coordinator and API layer. It does not reimplement mail or calendar protocols.

Storage

Files are the source of truth:

Data	Format	Sync Protocol
Email	Maildir	IMAP (via mbsync)
Tasks	VTODO (iCalendar)	CalDAV (via vdirsyncer)
Calendar events	VEVENT (iCalendar)	CalDAV (via vdirsyncer)
Contacts	vCard	CardDAV (via vdirsyncer)

SQLite indexes everything for fast queries, resolves dependency graphs, computes "what's actionable now." If the cache is lost, rebuild from files.

API

• REST (JSON) for all mutations (triage, compose, create task, defer, delegate, etc.)
• SSE for real-time push (new email arrived, deferred item resurfaced, delegated item timed out)
• Clean API enables multiple clients: macOS, iOS, web (future), CLI (future)

Clients

• macOS (SwiftUI) — primary, v1
• iOS (SwiftUI) — primary, v1
• Web — possible later
• CLI — theoretically possible since everything is files

---

Data Model

The Inbox

A unified queue of heterogeneous items:

• Emails arriving via IMAP
• Self-created tasks (VTODO)
• Delegated items returning with responses

Every item must be triaged: do / defer / delegate / file / discard.

Everything Is a Thread

The thread is the universal container:

• An email conversation is a thread
• A task with notes is a thread
• A project is a thread that grew (multiple tasks/emails linked together)
• The detail view always shows a threaded timeline mixing emails, tasks, notes, events

Tasks (VTODO)

Standard iCalendar VTODO with GTD enrichments:

Concept	VTODO Property
Title	SUMMARY
Description	DESCRIPTION (plain text)
Defer / hide-until date	DTSTART
Deadline	DUE
GTD contexts (@office, @phone)	CATEGORIES
Status	STATUS (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
Priority	PRIORITY (1-9)
Subtasks	RELATED-TO;RELTYPE=PARENT
Dependencies	RELATED-TO with FINISHTOSTART (RFC 9253)
Link to email	ATTACH:mid:<message-id>
Notifications	VALARM
Custom enrichments	X-properties (energy, time estimates, etc.)

Dependency-Driven Visibility

• If task B depends on task A, B is hidden until A is done
• Inbox / Today / Forecast views only show actionable items
• SQLite cache resolves the dependency graph

Projects

Projects emerge organically through progressive disclosure:

1. Any thread with 2+ tasks automatically becomes a project
2. Can be explicitly promoted early (even with one task)
3. Simple projects: just grouped tasks in a thread
4. Complex projects: add dependencies, milestones, phases as needed
5. Projects live in the sidebar under "Projects" and open as threads in the detail view

Delegation & Waiting Loop

Delegation is an active tracking loop, not fire-and-forget:

1. You delegate a task → Magnum Opus sends an email to the assignee
2. The item moves to "Waiting" with a link to the original thread
3. Each waiting item has an expected response window (configurable default + per-item override)
4. If the window expires without response, the item automatically resurfaces in your inbox
5. Assignee responses (email replies) are threaded back into the project context
6. Future: external portal via link in delegation email — assignees can update task status, attach files, mark done without a Magnum Opus account

Accounts

• Multi-account is a first-class concept in the data model
• v1 supports one account; architecture allows adding more
• Each account = one IMAP + one CalDAV + one CardDAV connection

Append-Only History

• No deletes. State changes are recorded like accounting entries.
• Full audit trail from the moment the user starts using Magnum Opus.
• Export-and-compact is the only mechanism to drop history:
  • Can be run on an interval (e.g., yearly)
  • Can be scoped per-project
  • Produces a clean snapshot of current state with no historical links

---

GUI

Layout

┌─────────────┬──────────────────┬─────────────────────────┐
│  SIDEBAR    │  ITEM LIST       │  DETAIL / THREAD VIEW   │
│             │                  │                         │
│  Inbox (3)  │  ✉ RE: Q1 plan  │  Threaded timeline:     │
│  Today      │  ☐ Draft spec   │   - Email from Alice    │
│  Upcoming   │  ✉ Invoice.pdf  │   - Your reply          │
│  Forecast   │  ☐ Review PR    │   - [Task: write spec]  │
│  Projects ▸ │                  │   - Email from Bob      │
│  Waiting    │                  │   - [Note: decided X]   │
│  Someday    │                  │   - [Event: meeting]    │
│  Archive    │                  │                         │
│  Tags ▸     │                  │                         │
│  Accounts ▸ │                  │                         │
└─────────────┴──────────────────┴─────────────────────────┘

Sidebar Perspectives

Perspective	Content
Inbox	Unprocessed items (emails + self-created tasks)
Today	Items deferred to today + items due today
Upcoming	Items with future defer/due dates
Forecast	Calendar view — events and dated tasks across all projects
Projects	All projects (threads with 2+ tasks)
Waiting	Delegated items with response tracking
Someday	Deferred indefinitely — review periodically
Archive	Processed items (filed, completed, discarded)
Tags	Filter by GTD contexts and categories
Accounts	Account management

Triage Workflow

• Keyboard-first: single keystrokes for do/defer/delegate/file/discard
• Swipe/buttons: always available for discoverability and iOS touch
• Keyboard is the soul of the interaction

Defer Options

• To a date (item disappears, reappears on that date)
• To a date + time (with notification)
• To a context (@office, @phone — appears when user is in that context)
• To a combination (date + context)

Calendar / Forecast

• Global forecast: "what does my week look like?" across all projects
• Per-project calendar: timeline of events and dated tasks within a project
• Per-task context: when is this due, what's blocking it

Compose (v1)

• Plain text replies, forwards, compose
• Rich text editor is a future enhancement

Contacts (v1)

• Display contact names and avatars from CardDAV in threads
• Autocomplete email addresses when composing
• No contact editing in v1

Standard Mail Client Compatibility

Opening the same IMAP account in Apple Mail or Thunderbird shows normal email. All task/project metadata lives in VTODO files via CalDAV, not inside the emails. The two data stores are linked by Message-ID references in VTODO ATTACH properties.

---

Technology Choices

Component	Technology	Rationale
Backend runtime	Node/Bun + Hono	Matches existing stack, good for API layer
IMAP sync	mbsync	Battle-tested Maildir sync
CalDAV/CardDAV sync	vdirsyncer	Standard file-based sync
Mail indexing	notmuch (or similar)	Xapian-based search over Maildir
Cache/index	SQLite	Fast queries, rebuildable, single file
API transport	REST + SSE	Simple mutations + real-time push
macOS/iOS client	SwiftUI	Native Apple experience
Deployment	Uberspace	Always-on, no Docker, shared hosting

---

v1 Scope

In

• Single account (IMAP + CalDAV + CardDAV)
• Unified inbox with email + task triage
• Full GTD workflow: do / defer / delegate / file / discard
• Defer to date, date+time, context, or combination
• Task dependencies with visibility filtering
• Projects via organic thread growth + explicit promotion
• Delegation with automatic resurfacing on timeout
• Waiting loop tracking
• Plain text compose/reply/forward
• Contact display + autocomplete
• Calendar/forecast view
• Keyboard-first triage with swipe/button fallback
• Append-only history
• macOS + iOS clients

Out (Future)

• Multiple accounts
• Rich text composer
• External delegation portal (web link for assignees)
• Contact editing
• Web client
• Advanced project views (Gantt, resource allocation)
• Recurring task support (poor ecosystem support)
• Export-and-compact tooling (can be manual/scripted initially)