# SP Mail Next — implementation plan
Branch next in both repositories (sp-mail, sp-mail-apple). main stays the production line until the release step. Status column is updated as work lands; the evidence for every « done » is in TEST-REPORT-NEXT.md.
Priorities, in order: reliability → synchronisation and push → design → productivity → intelligence → ecosystem → release. A decorative item never ships ahead of a correctness item in the same area.
# Phase 0 — Audit (done)
| Item |
Output |
| Read both repositories, working trees, deployment, tests, build configuration |
AUDIT-NEXT.md |
| Architecture decisions and server contract |
ARCHITECTURE-NEXT.md |
| Visual specification |
DESIGN-SYSTEM-NEXT.md |
Shared scaffold: server/src/next/ (routes, workers, in-transaction watcher hooks) |
commit « Next scaffold » |
# Phase 1 — Reliability
| # |
Work |
Where |
Audit refs |
| 1.1 |
Draft never lost on close/offline; list refresh around the viewport; stale ids; account-switch races; removed mailboxes torn down; stable mailbox routing |
web state |
R1–R5 |
| 1.2 |
Cache cleared on any session loss; height measurement inside the sandbox; trusted senders require aligned DKIM/DMARC |
web |
S1–S3 |
| 1.3 |
Email/queryChanges-based incremental list sync; selector cost independent of list size |
web |
P1, P3 |
| 1.4 |
Quote-mode sanitisation; lossless drafts; idempotent submission by Message-ID; safe retry; anchor-based paging; pending-queue error classification; resync keeps bodies and pending ops; joinable sync for background tasks |
SPMailCore |
R6–R12, R15 |
| 1.5 |
Outbox backoff; draft save coalescing and cross-device conflict (keep both); schema versioning; prepared statements; attachment cache; body prefetch; server threads; sync status model |
SPMailCore |
P2, P6, S5 |
| 1.6 |
Wrong-account folder list; removed mailboxes; app lock gating of every window; sanitiser off the main thread |
Apple UI |
R13, R14, S4, P5 |
| 1.7 |
Server-side APNs pipeline: token lifecycle, per-device and per-user preferences, durable dedup queue, retries, token cleanup, badge, quiet hours, priority senders, observability |
backend next/push.ts, next/apns.ts |
audit §2 |
| 1.8 |
Monitoring and alerts: queue, disk, certificates, backups, authentication anomalies, delivery degradation |
backend next/ops.ts |
S7 |
# Phase 2 — Design (« SP Mail Premium »)
| # |
Work |
Platform |
| 2.1 |
Tokens: light / dark / midnight, density, typography, motion, reduced motion/transparency, contrast |
web, Apple |
| 2.2 |
Shell: resizable and collapsible panes, sidebar hierarchy, conversation cards, contextual toolbars, skeletons, empty states, transitions |
web |
| 2.3 |
Command palette |
web, macOS |
| 2.4 |
Responsive tablet and phone layouts, bottom navigation, swipe gestures |
web |
| 2.5 |
macOS: translucent sidebar, inspector, customisable toolbar, command menus, multiple windows with restoration, menu bar extra |
macOS |
| 2.6 |
iPadOS: three columns, per-scene state, pointer and keyboard; iOS: thumb-friendly layout, swipe actions, haptics, Dynamic Type, VoiceOver |
iOS/iPadOS |
# Phase 3 — Productivity
| # |
Work |
Backend |
Clients |
| 3.1 |
Composer: rich text, inline images, attachment previews, multiple signatures, identity picker, contact autocomplete, snippets, template insertion, autosave, send later, undo send, send + remind, missing-attachment and sensitive-recipient checks |
v1/send.ts additions, next/organize.ts |
web, macOS, iOS |
| 3.2 |
Search: operator language, all mailboxes, saved searches / smart folders, filters, bulk operations |
next/search.ts, next/query.ts |
web, macOS, iOS |
| 3.3 |
Labels, pin, snooze, follow-up reminders |
next/snooze.ts, next/organize.ts |
web, macOS, iOS |
| 3.4 |
Contacts: profiles, history, favourites, groups, import/export, duplicates |
next/contacts.ts |
web, macOS, iOS |
| 3.5 |
Attachments: gallery, filters, previews, multi-download, drag into the composer |
next/search.ts (index, ZIP) |
web, macOS, iOS |
| 3.6 |
Command Center dashboard |
next/dashboard.ts |
web, macOS, iOS (+ widgets) |
| 3.7 |
Notifications in the apps: categories, actions (archive, mark read, reply), grouping, tap routing, per-device preferences |
— |
macOS, iOS |
| 3.8 |
Extensions: widgets, share extension, Spotlight continuation, App Intents |
— |
iOS, macOS |
| 3.9 |
Offline web: service worker (app shell), action queue |
— |
web |
# Phase 4 — Intelligence (optional layer, off by default)
| # |
Work |
| 4.1 |
Provider abstraction (local MacLustr inference, Anthropic), consent and disclosure, usage log, rate limits |
| 4.2 |
Smart summary, smart reply, writing assistant |
| 4.3 |
Intelligent inbox: model-free insights (newsletters, needs reply, unanswered) + optional triage |
| 4.4 |
Semantic and hybrid search with a local embedding model |
| 4.5 |
Client surfaces on the three platforms, always labelled with the provider, always reviewed before sending |
# Phase 5 — Ecosystem
| # |
Work |
| 5.1 |
Rules engine (post-delivery automation, idempotent, audited, never sends) |
| 5.2 |
Administration: health dashboard, alerts, device management, trends, security events, backup and certificate status |
| 5.3 |
API documentation, OpenAPI, SDK and MCP updates for the additive fields |
# Phase 6 — Release
- Full regression: backend, web unit, Playwright suites, SDK/MCP, Apple core, in-app self-tests; performance budgets measured against the baseline.
- Documentation:
FEATURE-PARITY.md, TEST-REPORT-NEXT.md, RELEASE-NEXT.md, README and API documentation.
- Production deployment only with the owner's authorisation, following
RELEASE-NEXT.md: verified backup, additive migrations, health checks, real send/receive check on the staging domain, rollback by git checkout of the previous commit (tables added by Next are ignored by 0.3.0).
- Apple: version 2.0.0, existing signing, notarisation and TestFlight scripts.
# Working rules
- Each parallel work stream has a strict file perimeter, its own port and its own test database; streams never commit — integration and commits are done centrally after review and a full test run.
- Tests run against the real stack (PostgreSQL, Stalwart, staging domain
stg.spboucher.ai); test mail is only exchanged between addresses created by the test run.
- No production change (deploy, DNS, Stalwart configuration, App Store Connect) happens as a side effect of development.