How monapdx/mailbreak works
1. What this repo is
- MailBreak is an offline Gmail archive browser. Its core purpose is to let a user inspect Google Takeout .mbox exports locally, without any backend, API calls, or cloud services.
2. Primary runtime
- The main application is a Python 3.10+ Streamlit app in mbox_viewer_streamlit.py.
- Streamlit provides the UI layer and local app runtime; the app is meant to run on the user’s machine.
3. Input boundary: Google Takeout
- The external data source is Gmail exported via Google Takeout.
- The architecture assumes the user first creates labels/filters in Gmail, exports selected mail, and then loads the resulting .mbox file into MailBreak.
4. Core data flow
- The mail archive flows from Takeout .mbox file → local parsing/inspection logic → Streamlit UI.
- The app’s responsibility is browsing and reading messages, not synchronizing with Gmail or modifying the mailbox in the cloud.
5. Main subsystem: Streamlit mailbox viewer
- mbox_viewer_streamlit.py is the central subsystem.
- It likely handles:
- file loading / selection
- mailbox parsing
- message listing or navigation
- rendering headers, HTML bodies, and plaintext bodies in the Streamlit interface
6. Alternative UI path
- email-viewer.html is a separate browser-based viewer.
- This suggests the repo offers an optional, more classic “message viewer” experience alongside the Streamlit app, likely as a standalone front-end for inspecting email content locally.
7. Documentation / operating model
- README.md and MailBreak-Instructions.pdf are supporting artifacts, not runtime components.
- They define the workflow: organize Gmail with labels, export only desired slices via Takeout, then open locally with MailBreak.
8. Important architectural boundary: offline and local-only
- The key design constraint is offline operation.
- All processing happens on the user’s device; there is no server tier, database, auth system, or remote persistence in the repository.
9. User workflow
- The user prepares mail in Gmail using labels/filters, exports via Takeout, then launches the local Streamlit app to browse the archive.
- This makes Gmail organization part of the effective upstream data model, even though it is external to the codebase.
10. What to draw in an architecture diagram
- Show three layers:
- External source: Gmail / Google Takeout
- Local processing/viewing: mbox_viewer_streamlit.py
- Optional alternate viewer: email-viewer.html
- Add documentation artifacts (README.md, PDF) as supporting assets, and emphasize that the whole system is single-user, local, and offline.
Main entry points: mbox_viewer_streamlit.py Streamlit app · MailBreak-Instructions.pdf Instructions · email-viewer.html HTML viewer · README.md README
Components 7
External source
Upstream Gmail export workflow that produces local mail archives.
- Gmail export · User-prepared Gmail mail selected and exported through Google Takeout.
- MBOX file · The exported .mbox archive that is loaded locally for browsing.
Local app
Offline tools that inspect the exported mailbox on the user’s machine.
- Streamlit app · Main offline Python application for loading, parsing, and browsing mailbox contents.
mbox_viewer_streamlit.py - HTML viewer · Standalone browser-based email viewer for local inspection of messages.
email-viewer.html - Offline mode · Local-only execution with no backend, sync service, or remote persistence.
Docs
Usage guidance and workflow documentation.
- README · Primary written overview of the workflow and project purpose.
README.md - Instructions · Detailed operating instructions for preparing and browsing exported mail.
MailBreak-Instructions.pdf
Connections 8
- Gmail export → MBOX file: exports · Google Takeout produces the local mailbox archive.
- MBOX file → Streamlit app: loads · The Streamlit app opens and parses the exported archive.
- MBOX file → HTML viewer: opens · The alternate HTML viewer renders messages from the same archive.
- Streamlit app → Offline mode: runs in · The main app executes entirely on the user’s device.
- HTML viewer → Offline mode: runs in · The alternate viewer is also local and offline.
- README → Streamlit app: documents · README explains the main app and workflow.
- Instructions → Gmail export: guides · Instructions describe how to prepare Gmail and export the archive.
- Instructions → Streamlit app: guides · Instructions cover launching and using the local viewer.