SPB Git

Repository Public

IMPLEMENTATION-PLAN.md 6.5 KB

# 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

  1. Full regression: backend, web unit, Playwright suites, SDK/MCP, Apple core, in-app self-tests; performance budgets measured against the baseline.
  2. Documentation: FEATURE-PARITY.md, TEST-REPORT-NEXT.md, RELEASE-NEXT.md, README and API documentation.
  3. 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).
  4. 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.
Files main
Menu

Theme