diff --git a/feasibility/README.md b/feasibility/README.md new file mode 100644 index 0000000..8d515e4 --- /dev/null +++ b/feasibility/README.md @@ -0,0 +1,35 @@ +# Feasibility Reports for IDEAS.md + +This folder contains feasibility reports for each execution-mode idea described in [`IDEAS.md`](../IDEAS.md). The reports assume the current project status from [`README.md`](../README.md): Flat Email is still in the design/specification stage, with the archive layout defined in [`SPEC.md`](../SPEC.md). + +## Reports + +### Delivery / output targets + +- [Email 2 Filesystem](email-2-filesystem.md) +- [Email 2 Repo](email-2-repo.md) +- [Email 2 Cloud Filesystem](email-2-cloud-filesystem.md) +- [Email 2 Encrypted Vault](email-2-encrypted-vault.md) +- [Email 2 Database / Index sink](email-2-database-index-sink.md) + +### Packaged applications + +- [Windows app](windows-app.md) +- [Linux app](linux-app.md) +- [macOS app](macos-app.md) +- [Mobile companions](mobile-companions.md) +- [Cross-platform desktop shell](cross-platform-desktop-shell.md) + +### Service & integration modes + +- [Local Email MCP server](local-email-mcp-server.md) +- [Local HTTP API + serverless reader](local-http-api-serverless-reader.md) +- [Daemon / scheduled sync service](daemon-scheduled-sync-service.md) +- [Container / self-hosted server image](container-self-hosted-server-image.md) +- [Library / SDK](library-sdk.md) + +### Connector / input modes + +- [More providers](more-providers.md) +- [Local mail stores](local-mail-stores.md) +- [Push / streaming ingest](push-streaming-ingest.md) diff --git a/feasibility/container-self-hosted-server-image.md b/feasibility/container-self-hosted-server-image.md new file mode 100644 index 0000000..f8f71a6 --- /dev/null +++ b/feasibility/container-self-hosted-server-image.md @@ -0,0 +1,26 @@ +# Feasibility Report: Container / Self-hosted Server Image + +## Verdict + +Feasible and valuable for NAS/home-lab users once the CLI exists. + +## Rationale + +A container can package sync, local API, MCP, and reader serving in a repeatable deployment. It fits server and NAS use cases, but it depends on clear volume, secrets, and update practices. + +## Dependencies + +- Headless CLI operation. +- Environment or mounted-file configuration format. +- Volume layout for archive data and non-archive sync state. +- Secret injection that avoids storing tokens in image layers or archives. + +## Key risks + +- Users may expose private mail APIs publicly. +- File ownership and permissions can be difficult across host platforms. +- Token persistence and refresh flows are harder in headless containers. + +## Recommendation + +Ship after local sync and serve commands work. Default to loopback/private binding, document reverse-proxy risks, and keep secrets outside mounted archive paths. diff --git a/feasibility/cross-platform-desktop-shell.md b/feasibility/cross-platform-desktop-shell.md new file mode 100644 index 0000000..01d0fa7 --- /dev/null +++ b/feasibility/cross-platform-desktop-shell.md @@ -0,0 +1,26 @@ +# Feasibility Report: Cross-platform Desktop Shell + +## Verdict + +Feasible and likely preferable to three bespoke desktop apps. + +## Rationale + +A Tauri, Electron, or Wails shell can reuse the serverless reader and call the same sync core across Windows, macOS, and Linux. This reduces duplicated UI work while still enabling native credential storage and background helpers. + +## Dependencies + +- Stable command or library interface for sync operations. +- Reusable web reader UI. +- Cross-platform credential abstraction. +- Packaging and update strategy for all target operating systems. + +## Key risks + +- Less native feel than bespoke apps. +- Framework choice affects binary size, security surface, and update complexity. +- OS-specific background scheduling still requires platform code. + +## Recommendation + +Use this as the default desktop strategy once the CLI and reader are proven. Keep OS-specific apps out of scope unless user demand justifies them. diff --git a/feasibility/daemon-scheduled-sync-service.md b/feasibility/daemon-scheduled-sync-service.md new file mode 100644 index 0000000..800d20a --- /dev/null +++ b/feasibility/daemon-scheduled-sync-service.md @@ -0,0 +1,27 @@ +# Feasibility Report: Daemon / Scheduled Sync Service + +## Verdict + +Feasible after incremental sync and locking are reliable. + +## Rationale + +Scheduled sync is a natural extension of a CLI sync command and unlocks set-and-forget archiving. It should not be implemented until idempotency, sync state, and failure recovery are well-defined. + +## Dependencies + +- Incremental sync cursors and retryable provider operations. +- Archive locking to prevent concurrent writes. +- Backoff, logging, health status, and error reporting. +- OS-specific schedulers or a portable long-running process. + +## Key risks + +- Corruption from overlapping sync runs. +- Hidden failures if background jobs cannot notify users. +- Provider rate limits and auth refresh failures. +- Confusing semantics for deletions and label changes over time. + +## Recommendation + +Begin with documented scheduler integrations around the CLI. Add a long-running daemon only after the sync engine can recover safely from interruption. diff --git a/feasibility/email-2-cloud-filesystem.md b/feasibility/email-2-cloud-filesystem.md new file mode 100644 index 0000000..65f9a17 --- /dev/null +++ b/feasibility/email-2-cloud-filesystem.md @@ -0,0 +1,27 @@ +# Feasibility Report: Email 2 Cloud Filesystem + +## Verdict + +Moderately feasible, best implemented behind a storage backend abstraction. + +## Rationale + +Object stores and consumer sync folders are natural destinations for a portable archive, but they differ sharply from local filesystems in consistency, latency, listing semantics, and credential handling. + +## Dependencies + +- Storage interface that can write, read, list, and atomically publish archive paths where possible. +- Manifest or catalog design that avoids excessive small-object reads. +- Provider-specific credential storage and configuration. +- Clear guidance for sync-folder providers versus direct object-store APIs. + +## Key risks + +- High cost or poor performance from many small files in object storage. +- Eventual consistency causing partial archive reads during sync. +- Remote credential exposure or accidental public buckets. +- Conflicts when multiple machines sync to the same destination. + +## Recommendation + +Support synced local folders first because the filesystem implementation already covers them. Add S3-compatible object storage next, with conservative write ordering and explicit warnings about encryption and public access. diff --git a/feasibility/email-2-database-index-sink.md b/feasibility/email-2-database-index-sink.md new file mode 100644 index 0000000..dd89f3b --- /dev/null +++ b/feasibility/email-2-database-index-sink.md @@ -0,0 +1,25 @@ +# Feasibility Report: Email 2 Database / Index Sink + +## Verdict + +Feasible as an optional, regenerable acceleration layer. + +## Rationale + +A database or search index can improve query speed and analytics without compromising the flat-file mission if it is always rebuildable from the archive. This aligns with `SPEC.md`, which already treats indexes as derived. + +## Dependencies + +- Stable metadata and catalog schema. +- Rebuild command that can recreate the index from `message.eml` and derived metadata. +- Clear separation between archive correctness and index availability. + +## Key risks + +- Users may start depending on the database as the source of truth. +- Schema migrations add maintenance overhead. +- External search engines complicate installation and portability. + +## Recommendation + +Begin with an embedded SQLite or Tantivy-style local index after filesystem sync works. Keep all index files under a clearly regenerable path and make archive browsing work without them. diff --git a/feasibility/email-2-encrypted-vault.md b/feasibility/email-2-encrypted-vault.md new file mode 100644 index 0000000..5b8fbec --- /dev/null +++ b/feasibility/email-2-encrypted-vault.md @@ -0,0 +1,27 @@ +# Feasibility Report: Email 2 Encrypted Vault + +## Verdict + +Feasible but higher risk than plain storage modes. + +## Rationale + +Encryption at rest strongly matches the sensitivity of email archives, especially for cloud and Git destinations. The hard part is preserving usability, searchability, and recovery while avoiding bespoke cryptography. + +## Dependencies + +- Storage layer where encryption can be inserted transparently. +- Choice of established encryption format and key-management approach, such as age or GPG. +- Decision on whether paths, filenames, metadata, and indexes are encrypted. +- Recovery and rotation story for archive keys. + +## Key risks + +- Search becomes difficult if contents and indexes are encrypted. +- Directory structure may leak sensitive metadata even if file contents are encrypted. +- Lost keys mean permanent data loss. +- Cross-platform UX for key management can become complex. + +## Recommendation + +Defer until the core archive and storage abstraction are stable. Start with whole-file content encryption using a proven tool, document metadata leakage clearly, and avoid custom cryptographic design. diff --git a/feasibility/email-2-filesystem.md b/feasibility/email-2-filesystem.md new file mode 100644 index 0000000..d046199 --- /dev/null +++ b/feasibility/email-2-filesystem.md @@ -0,0 +1,25 @@ +# Feasibility Report: Email 2 Filesystem + +## Verdict + +Highly feasible and foundational. + +## Rationale + +This is the baseline product shape described by the README and formalised by `SPEC.md`. The repository is currently in design stage, so the main work is implementing the already-documented archive writer rather than inventing a new delivery mode. + +## Dependencies + +- Stable archive layout and schema conformance. +- Deterministic writer for raw messages, derived metadata, bodies, labels, threads, catalog files, and reader HTML. +- Golden archive tests that verify byte-stable output. + +## Key risks + +- Email edge cases such as malformed MIME, missing headers, duplicate attachment names, and odd encodings. +- Accidental non-determinism in generated JSON or HTML. +- Blurring the boundary between authoritative `message.eml` and derived files. + +## Recommendation + +Implement this first. Treat it as the acceptance target for every other idea: if a mode cannot preserve this layout and its determinism guarantees, it should wait. diff --git a/feasibility/email-2-repo.md b/feasibility/email-2-repo.md new file mode 100644 index 0000000..4fdab10 --- /dev/null +++ b/feasibility/email-2-repo.md @@ -0,0 +1,27 @@ +# Feasibility Report: Email 2 Repo + +## Verdict + +Feasible after the filesystem baseline is deterministic. + +## Rationale + +A Git-backed archive is mostly orchestration around the flat filesystem output. It becomes valuable only if repeat syncs produce meaningful diffs, so it depends directly on stable paths, sorted metadata, and deterministic derived files. + +## Dependencies + +- Completed local filesystem sync mode. +- Clear policy for derived files and regenerable indexes in `.gitignore`. +- Safe handling for large attachments, likely through Git LFS or content-addressed storage. +- Credential and token storage outside the archive and repository. + +## Key risks + +- Huge repository growth from attachments and generated HTML. +- Privacy leaks if archives are pushed to remotes without clear warnings. +- Noisy commits if derived files are not byte-stable. +- Ambiguous commit semantics for label changes, deletions, and re-renders. + +## Recommendation + +Prototype as a thin wrapper around filesystem sync with local-only commits first. Add optional remote push only after size, ignore rules, and safety prompts are defined. diff --git a/feasibility/library-sdk.md b/feasibility/library-sdk.md new file mode 100644 index 0000000..bdf8f79 --- /dev/null +++ b/feasibility/library-sdk.md @@ -0,0 +1,26 @@ +# Feasibility Report: Library / SDK + +## Verdict + +Feasible after the archive format stabilises. + +## Rationale + +An SDK can let other tools produce and consume Flat Email archives, but publishing it too early risks freezing unstable abstractions. The layout spec should lead; the SDK should encode it. + +## Dependencies + +- Stable `SPEC.md` and schema versions. +- Conformance fixtures and compatibility tests. +- Clear separation between archive writer, parser, connector, and reader concerns. +- Versioning policy for breaking format changes. + +## Key risks + +- Premature public APIs can slow necessary format changes. +- Multiple implementations may diverge without strong conformance tests. +- Language choice may limit ecosystem adoption. + +## Recommendation + +Create internal library boundaries first, then publish an SDK once v1 archive semantics and conformance tests are stable. diff --git a/feasibility/linux-app.md b/feasibility/linux-app.md new file mode 100644 index 0000000..982fb5c --- /dev/null +++ b/feasibility/linux-app.md @@ -0,0 +1,26 @@ +# Feasibility Report: Linux App + +## Verdict + +Feasible, especially as CLI plus service packaging. + +## Rationale + +Linux aligns well with filesystem-native archives, headless servers, NAS deployments, systemd timers, and plain-file tooling. GUI packaging can come later; the immediate value is robust CLI distribution. + +## Dependencies + +- Single-binary or simple packageable runtime. +- Systemd unit/timer examples for scheduled sync. +- Secret Service or keyring integration for credentials. +- Package metadata for AppImage, Flatpak, Snap, `.deb`, or `.rpm` channels. + +## Key risks + +- Packaging fragmentation across distributions. +- Desktop sandbox permissions for Flatpak/Snap. +- Keyring availability on headless systems. + +## Recommendation + +Support Linux early through CLI binaries and documented systemd timers. Treat GUI app packaging as secondary to reliable server/NAS operation. diff --git a/feasibility/local-email-mcp-server.md b/feasibility/local-email-mcp-server.md new file mode 100644 index 0000000..dcb8f72 --- /dev/null +++ b/feasibility/local-email-mcp-server.md @@ -0,0 +1,26 @@ +# Feasibility Report: Local Email MCP Server + +## Verdict + +Highly feasible after archive query primitives exist. + +## Rationale + +MCP can expose search, message retrieval, thread lookup, labels, and attachments over the local archive without changing the archive format. It is a strong fit for Flat Email's automation and ownership goals. + +## Dependencies + +- Efficient archive search and metadata lookup. +- Read-only tool definitions by default. +- Permission and redaction model for sensitive mail. +- Clear handling of attachment access and large result sets. + +## Key risks + +- Overexposure of sensitive mail to connected assistants. +- Poor ranking or pagination could make search tools noisy. +- Action tools such as reply/delete would undermine the read-only guarantee if added too early. + +## Recommendation + +Implement as read-only after local search works. Require explicit archive paths and keep tool outputs scoped, paginated, and privacy-conscious. diff --git a/feasibility/local-http-api-serverless-reader.md b/feasibility/local-http-api-serverless-reader.md new file mode 100644 index 0000000..ca10516 --- /dev/null +++ b/feasibility/local-http-api-serverless-reader.md @@ -0,0 +1,26 @@ +# Feasibility Report: Local HTTP API + Serverless Reader + +## Verdict + +Highly feasible and central to the product experience. + +## Rationale + +The API and reader are already part of the target design. The per-message HTML reader is especially aligned with the flat-file mission, while the local HTTP API can cover browser limitations and large-archive performance. + +## Dependencies + +- Catalog and metadata generation from the archive. +- Safe HTML rendering and remote-content blocking. +- Local-only server defaults with explicit host binding. +- API routes for messages, threads, labels, attachments, and search. + +## Key risks + +- `file://` limitations may constrain the serverless root reader. +- XSS and tracking risks from untrusted email HTML. +- Serving private mail over a network interface by accident. + +## Recommendation + +Prototype the reader early against real browsers. Keep per-message `email.html` self-contained, and use the HTTP API as the scalable path for full-archive browsing and search. diff --git a/feasibility/local-mail-stores.md b/feasibility/local-mail-stores.md new file mode 100644 index 0000000..b4d7cd9 --- /dev/null +++ b/feasibility/local-mail-stores.md @@ -0,0 +1,26 @@ +# Feasibility Report: Local Mail Stores + +## Verdict + +Highly feasible and an excellent first connector milestone. + +## Rationale + +Importing `.mbox`, Maildir, Apple Mail, Outlook archives, and Thunderbird profiles avoids OAuth, network failures, and rate limits. It lets the project validate the archive layout against real messages while preserving read-only behavior. + +## Dependencies + +- Parsers for one or more local mail formats. +- Mapping from local folders/profile metadata to Flat Email labels and accounts. +- Robust MIME handling and attachment extraction. +- Golden tests with representative local-store fixtures. + +## Key risks + +- Outlook `.pst`/`.ost` support may require complex or platform-specific parsing. +- Apple Mail and Thunderbird profiles can vary by version. +- Large historical stores may reveal performance issues early. + +## Recommendation + +Start with Maildir or `.mbox` for v0.1 because they are simpler, offline, and testable. Treat Outlook and app-specific profile imports as later compatibility work. diff --git a/feasibility/macos-app.md b/feasibility/macos-app.md new file mode 100644 index 0000000..01be1f3 --- /dev/null +++ b/feasibility/macos-app.md @@ -0,0 +1,27 @@ +# Feasibility Report: macOS App + +## Verdict + +Feasible but operationally more complex than CLI distribution. + +## Rationale + +macOS users benefit from Keychain, launchd, Spotlight indexing, and a polished menu-bar app. However, notarisation, sandboxing, filesystem permissions, and update distribution introduce overhead that should wait for a stable core. + +## Dependencies + +- Stable CLI or embeddable sync core. +- Keychain integration. +- Notarised and signed `.app` build pipeline. +- Filesystem access design that works with macOS privacy prompts. +- launchd scheduling for background sync. + +## Key risks + +- Sandboxing may conflict with user-selected archive folders. +- Notarisation failures can block releases. +- Background agent UX needs careful error reporting. + +## Recommendation + +Offer a CLI/Homebrew path first. Build a macOS app after the cross-platform reader and sync flow are proven. diff --git a/feasibility/mobile-companions.md b/feasibility/mobile-companions.md new file mode 100644 index 0000000..fff0238 --- /dev/null +++ b/feasibility/mobile-companions.md @@ -0,0 +1,26 @@ +# Feasibility Report: Mobile Companions + +## Verdict + +Read-only companions are moderately feasible; full mobile sync is low feasibility initially. + +## Rationale + +Browsing an existing archive on a phone matches the mission, but mobile filesystems, background execution, provider auth, and large local datasets make full sync difficult. A PWA or thin native wrapper around the reader is a better first step. + +## Dependencies + +- Archive reader that works with constrained local or cloud-backed files. +- Mobile-friendly UI and search experience. +- Integration with Files app, Android storage providers, or cloud storage SDKs. +- Clear offline caching strategy. + +## Key risks + +- Mobile browsers may restrict local file access even more than desktop browsers. +- Large mail archives can exceed device storage and indexing limits. +- Background sync is heavily constrained by iOS and Android lifecycle rules. + +## Recommendation + +Start with read-only browsing of an archive stored in a synced folder or cloud provider. Do not attempt mobile-first syncing until desktop/server sync is mature. diff --git a/feasibility/more-providers.md b/feasibility/more-providers.md new file mode 100644 index 0000000..5854702 --- /dev/null +++ b/feasibility/more-providers.md @@ -0,0 +1,27 @@ +# Feasibility Report: More Providers + +## Verdict + +Moderately feasible, but should follow a proven connector abstraction. + +## Rationale + +Yahoo, Proton via Bridge, Fastmail, POP3, and JMAP expand coverage, but each provider has different auth, folder, label, rate-limit, and message identity semantics. The flat archive can absorb those differences only if the connector interface is disciplined. + +## Dependencies + +- Provider-neutral message, label, thread, and deletion model. +- Read-only connector contract. +- Auth storage outside the archive. +- Test fixtures for provider-specific edge cases. + +## Key risks + +- Provider APIs and policies change over time. +- Proton support may depend on a local bridge rather than direct API access. +- POP3 lacks rich labels and stable sync semantics. +- JMAP support depends on server adoption and capability variation. + +## Recommendation + +Add providers one at a time after one offline import path and one network provider are working. Prefer standards-based IMAP/JMAP before highly custom APIs unless demand is clear. diff --git a/feasibility/push-streaming-ingest.md b/feasibility/push-streaming-ingest.md new file mode 100644 index 0000000..d65f7a9 --- /dev/null +++ b/feasibility/push-streaming-ingest.md @@ -0,0 +1,27 @@ +# Feasibility Report: Push / Streaming Ingest + +## Verdict + +Lower feasibility for early versions; valuable later. + +## Rationale + +Near-real-time ingest through SMTP sinks, Gmail watch, or Microsoft Graph subscriptions can keep archives current, but it introduces always-on infrastructure, webhook security, provider-specific renewal, and more complex state handling. + +## Dependencies + +- Mature incremental sync engine. +- Secure webhook or local listener deployment model. +- Provider subscription renewal and backfill logic. +- Durable queueing so missed events do not lose messages. + +## Key risks + +- Push notifications are often hints, not full message payloads, so polling/backfill remains necessary. +- Public webhooks increase security exposure. +- SMTP sink operation can blur the line between archive and mail server. +- Missed events can silently desynchronise the archive without reconciliation. + +## Recommendation + +Defer until polling sync is reliable. When added, use push only as a trigger for normal incremental sync, not as the sole source of truth. diff --git a/feasibility/windows-app.md b/feasibility/windows-app.md new file mode 100644 index 0000000..30d7645 --- /dev/null +++ b/feasibility/windows-app.md @@ -0,0 +1,26 @@ +# Feasibility Report: Windows App + +## Verdict + +Feasible after a working CLI/core exists, but not an early milestone. + +## Rationale + +A Windows GUI, installer, background sync, and Credential Manager integration would broaden adoption, but they wrap the core rather than prove it. The current repository is still at specification stage, so native packaging would be premature. + +## Dependencies + +- Stable sync core and local archive reader. +- GUI shell or webview strategy. +- Windows Credential Manager integration. +- Installer, code-signing certificate, auto-update, and background scheduling approach. + +## Key risks + +- Code signing and auto-update operational overhead. +- Background sync reliability across sleep, network changes, and account errors. +- Antivirus false positives for unsigned or uncommon binaries. + +## Recommendation + +Defer until the CLI is useful. Prefer a shared cross-platform shell before committing to a bespoke Windows app unless Windows-specific distribution becomes the primary goal.