Mailspring Documentation using BMAD approach by talekarnishita · Pull Request #2588 · Foundry376/Mailspring

talekarnishita · 2026-02-03T18:27:20Z

This folder contains the complete documentation set for the Mailspring "Dual-Core" architecture, reverse-engineered using the BMAD framework.

The documentation is organized into three phases: Phase 1 (Big Picture), Phase 2 (Mechanics), and Phase 3 (Analysis).

📋 Reviewer Reading Guide

To understand the system architecture effectively, please review the documents in the following order:

1. The Roadmap

PLAN.md: The master plan and checklist used to generate these artifacts. Start here to see the scope of work.
CLAUDE.md: The existing high-level summary (updated/referenced).

2. Phase 1: The Big Picture (Architecture)

docs/architecture/current-state.md: The core narrative explaining the "Dual-Core" design (Electron frontend + C++ backend).
docs/architecture/diagrams/system-context.md: High-level C4 diagram showing Mailspring and its external providers (Gmail, O365, etc.).
docs/architecture/diagrams/containers.md: C4 Container diagram showing the process boundaries (Renderer, Main, Mailsync, SQLite).

3. Phase 2: The Mechanics (How it works)

docs/architecture/data-flow.md: Traces the critical path of data from the Internet → C++ Engine → SQLite → Electron UI.
docs/architecture/data-model.md: (New) ER Diagram showing the database schema (Threads, Messages, Contacts) derived from Flux models.
docs/guides/debugging-dual-core.md: (New) Essential guide for debugging the C++ bridge and inspecting stdin/stdout traffic.
docs/architecture/module-dependencies.md: Explains how Flux stores (DatabaseStore, Actions) interact with the Mailsync Bridge.

4. Phase 3: Analysis & Decisions

docs/adr/: Retrospective Architecture Decision Records explaining why the system is built this way.
- 0001-split-engine-architecture.md (Why C++?)
- 0002-local-first-strategy.md (Why local SQLite?)
docs/technical-debt.md: A prioritized register of TODOs and legacy patterns found in the codebase.

📂 File Structure Overview

File / Folder	Description
`docs/architecture/diagrams/`	Mermaid.js source files for all C4 diagrams.
`docs/architecture/deployment.md`	Details on the build pipeline, signing, and packaging (macOS/Windows/Linux).
`docs/architecture/technology-stack.md`	Inventory of versions (Electron, Node, C++) and build tools.
`docs/architecture/integration-points.md`	Documentation of external protocols (IMAP, SMTP) and OAuth flows.

…ebt, review-submission

indent-staging · 2026-02-03T18:27:23Z

Issues

2 potential issues found:

The PR adds ~280 files of BMAD framework tooling (.cursor/commands/, _bmad/) that is a generic AI agent framework, not specific to Mailspring. This adds ~40K+ lines of repository bloat with tooling unrelated to the email client.
Moving SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and LICENSE.md to docs/ will break GitHub's automatic detection of these files. GitHub expects them at the repository root for special features like license display, security policy, and contributor guidelines. Additionally, CLAUDE.md should stay at root for Claude Code to find it.

Resolved (1 issue)

Minor remaining duplication: PLAN.md exists at both root and BMAD/PLAN.md, and docs/technical-debt.md is duplicated in BMAD/docs/technical-debt.md. Good progress - the _bmad/ duplication was resolved! (fixed by commit 1c36156)

Summary

This PR adds comprehensive architecture documentation for Mailspring's dual-core (Electron + C++) design and reorganizes existing documentation.

Adds architecture documentation in docs/architecture/ covering the dual-core design, data flow, technology stack, deployment, and data model with Mermaid diagrams
Adds a technical debt register (docs/technical-debt.md) cataloging TODO/FIXME items with priority and effort estimates
Adds .cursor/commands/ (41 files) for Cursor IDE AI agent workflows
Adds docs/README.md as an index for all documentation
Moves some root docs to docs/: CODE_OF_CONDUCT, CONTRIBUTING, LOCALIZATION, PLUGIN_SYSTEM_ARCHITECTURE, SECURITY, LICENSE, CLAUDE
CHANGELOG.md stays at root
Adds BMAD/ to .gitignore (local tooling folder)
Includes merge from master with accessibility plans, community plugin/theme docs, and various improvements

CI Checks

Waiting for CI checks...

Rule Checks 3 rules evaluated, 3 passed, 0 failed

Passing rules

This is a longer title to see what happens when they are too long to fit
B
Ben Rule

…ew-submission/

bengotow · 2026-02-07T19:27:55Z

Hey thanks for contributing this! I think I agree with Indent re: the duplication of the generated documentation and all of the tooling files. Happy to accept the architectural documentation if you can split it out from the other stuff going on here. There are a few existing files like PLUGIN_SYSTEM_ARCHITECTURE.md that should probably go into a new docs folder too.

talekarnishita · 2026-02-09T15:51:51Z

Hey Yep, that’s fair, I agree on the duplication concern. I’ll split out the architectural documentation and keep the rest out of this PR. I’ll also move existing files like PLUGIN_SYSTEM_ARCHITECTURE.md into a new docs/ directory so everything lives in one place. Will push an update shortly. Best Regards, Nishita Talekar

…

On Sun, Feb 8, 2026 at 12:58 AM Ben Gotow ***@***.***> wrote: *bengotow* left a comment (Foundry376/Mailspring#2588) <#2588 (comment)> Hey thanks for contributing this! I think I agree with Indent re: the duplication of the generated documentation and all of the tooling files. Happy to accept the architectural documentation if you can split it out from the other stuff going on here. There are a few existing files like PLUGIN_SYSTEM_ARCHITECTURE.md that should probably go into a new docs folder too. — Reply to this email directly, view it on GitHub <#2588 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BN47A3K3Q4OKFGCU36QBUC34KY4FDAVCNFSM6AAAAACT3LRYQWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNRVGE2DGNBYHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

Co-authored-by: Cursor <[email protected]>

…, LOCALIZATION, CONTRIBUTING to docs/ Co-authored-by: Cursor <[email protected]>

Co-authored-by: Cursor <[email protected]>

talekarnishita · 2026-02-12T12:59:50Z

Hi, I’ve moved all the Markdown files to the root docs folder, created a README for it, and removed all unnecessary and duplicate files—keeping only the architecture-related files. I’ve pushed the changes. Best regards, Nishita Talekar On Mon, Feb 9, 2026 at 9:21 PM nishita talekar ***@***.***> wrote:

…

Hey Yep, that’s fair, I agree on the duplication concern. I’ll split out the architectural documentation and keep the rest out of this PR. I’ll also move existing files like PLUGIN_SYSTEM_ARCHITECTURE.md into a new docs/ directory so everything lives in one place. Will push an update shortly. Best Regards, Nishita Talekar On Sun, Feb 8, 2026 at 12:58 AM Ben Gotow ***@***.***> wrote: > *bengotow* left a comment (Foundry376/Mailspring#2588) > <#2588 (comment)> > > Hey thanks for contributing this! I think I agree with Indent re: the > duplication of the generated documentation and all of the tooling files. > Happy to accept the architectural documentation if you can split it out > from the other stuff going on here. There are a few existing files like > PLUGIN_SYSTEM_ARCHITECTURE.md that should probably go into a new docs > folder too. > > — > Reply to this email directly, view it on GitHub > <#2588 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BN47A3K3Q4OKFGCU36QBUC34KY4FDAVCNFSM6AAAAACT3LRYQWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNRVGE2DGNBYHE> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

talekarnishita · 2026-02-12T13:00:01Z

Hi, I’ve moved all the Markdown files to the root docs folder, created a README for it, and removed all unnecessary and duplicate files—keeping only the architecture-related files. I’ve pushed the changes.

Co-authored-by: Cursor <[email protected]>

talekarnishita added 2 commits February 3, 2026 23:41

Add BMAD documentation: PLAN, architecture, guides, ADRs, technical d…

8700a50

…ebt, review-submission

chore: add bmad artifacts and cursor plans

b9d8700

talekarnishita added 3 commits February 4, 2026 00:54

Add BMAD folder with documentation deliverables

ecefa01

BMAD: update folder structure in README to show BMAD/ instead of revi…

0637362

…ew-submission/

Add _bmad framework into BMAD folder

fc0e3ce

talekarnishita and others added 15 commits February 12, 2026 17:48

chore: remove review-submission folder (duplicate docs)

e723ed7

Co-authored-by: Cursor <[email protected]>

Remove docs/adr, docs/architecture, and docs/guides

5c29811

Co-authored-by: Cursor <[email protected]>

Remove BMAD/_bmad

2dffc8a

Co-authored-by: Cursor <[email protected]>

Remove _bmad and _bmad-output from git; add to .gitignore

8ea6bfa

Co-authored-by: Cursor <[email protected]>

Remove PLAN.md from git; add to .gitignore

1c36156

Co-authored-by: Cursor <[email protected]>

Remove PLAN.md from .gitignore (file removed entirely)

d8a1f7d

Co-authored-by: Cursor <[email protected]>

Remove BMAD entries from .gitignore

a89bbbc

Co-authored-by: Cursor <[email protected]>

Remove BMAD/CLAUDE.md and BMAD/PLAN.md

7adc359

Co-authored-by: Cursor <[email protected]>

Move architecture docs from BMAD/docs/architecture to docs/architecture

76fcff9

Co-authored-by: Cursor <[email protected]>

update

3d314e3

update

3a30bdb

Remove BMAD from git; add to .gitignore

1320fc0

Co-authored-by: Cursor <[email protected]>

Move SECURITY, PLUGIN_SYSTEM_ARCHITECTURE, CODE_OF_CONDUCT, CHANGELOG…

f2327f5

…, LOCALIZATION, CONTRIBUTING to docs/ Co-authored-by: Cursor <[email protected]>

Move CLAUDE.md and LICENSE.md to docs/

119c27b

Co-authored-by: Cursor <[email protected]>

update

1059e52

talekarnishita and others added 3 commits February 12, 2026 18:37

Merge remote-tracking branch 'upstream/master'

df3867f

Move CHANGELOG.md back to repo root

10ca7f5

Co-authored-by: Cursor <[email protected]>

Merge branch 'master' into docs

b66ac32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mailspring Documentation using BMAD approach#2588

Mailspring Documentation using BMAD approach#2588
talekarnishita wants to merge 23 commits intoFoundry376:masterfrom
talekarnishita:docs

talekarnishita commented Feb 3, 2026 •

edited

Loading

Uh oh!

indent-staging bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

bengotow commented Feb 7, 2026

Uh oh!

talekarnishita commented Feb 9, 2026 via email

Uh oh!

talekarnishita commented Feb 12, 2026 via email

Uh oh!

talekarnishita commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

talekarnishita commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Reviewer Reading Guide

1. The Roadmap

2. Phase 1: The Big Picture (Architecture)

3. Phase 2: The Mechanics (How it works)

4. Phase 3: Analysis & Decisions

📂 File Structure Overview

Uh oh!

indent-staging bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bengotow commented Feb 7, 2026

Uh oh!

talekarnishita commented Feb 9, 2026 via email

Uh oh!

talekarnishita commented Feb 12, 2026 via email

Uh oh!

talekarnishita commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

talekarnishita commented Feb 3, 2026 •

edited

Loading

indent-staging bot commented Feb 3, 2026 •

edited

Loading