# monapdx/mailbreak architecture

> Architecture diagram of the GitHub repository monapdx/mailbreak, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monapdx/mailbreak
- Repository: https://github.com/monapdx/mailbreak

## Overview

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`](https://github.com/monapdx/mailbreak/blob/main/mbox_viewer_streamlit.py) (Streamlit app), [`MailBreak-Instructions.pdf`](https://github.com/monapdx/mailbreak/blob/main/MailBreak-Instructions.pdf) (Instructions), [`email-viewer.html`](https://github.com/monapdx/mailbreak/blob/main/email-viewer.html) (HTML viewer), [`README.md`](https://github.com/monapdx/mailbreak/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External source"]
  node_gmail_takeout[("Gmail export<br/>external source")]
  node_mbox_archive["MBOX file<br/>mail archive"]
end

subgraph group_local["Local app"]
  node_streamlit_viewer["Streamlit app<br/>viewer"]
  node_html_viewer["HTML viewer<br/>alternate viewer<br/>[email-viewer.html]"]
  node_local_offline(("Offline mode<br/>runtime boundary"))
end

subgraph group_docs["Docs"]
  node_readme["README<br/>usage guide<br/>[README.md]"]
  node_instructions_pdf["Instructions<br/>workflow guide"]
end

node_gmail_takeout -->|"exports"| node_mbox_archive
node_mbox_archive -->|"loads"| node_streamlit_viewer
node_mbox_archive -->|"opens"| node_html_viewer
node_streamlit_viewer -->|"runs in"| node_local_offline
node_html_viewer -->|"runs in"| node_local_offline
node_readme -.->|"documents"| node_streamlit_viewer
node_instructions_pdf -.->|"guides"| node_gmail_takeout
node_instructions_pdf -.->|"guides"| node_streamlit_viewer

click node_streamlit_viewer "https://github.com/monapdx/mailbreak/blob/main/mbox_viewer_streamlit.py"
click node_html_viewer "https://github.com/monapdx/mailbreak/blob/main/email-viewer.html"
click node_readme "https://github.com/monapdx/mailbreak/blob/main/README.md"
click node_instructions_pdf "https://github.com/monapdx/mailbreak/blob/main/MailBreak-Instructions.pdf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gmail_takeout,node_mbox_archive toneBlue
class node_streamlit_viewer,node_html_viewer,node_local_offline toneAmber
class node_readme,node_instructions_pdf toneMint
```

## Components

### External source

Upstream Gmail export workflow that produces local mail archives.

- **Gmail export**: external source · User-prepared Gmail mail selected and exported through Google Takeout.
- **MBOX file**: mail archive · 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](https://github.com/monapdx/mailbreak/blob/main/mbox_viewer_streamlit.py): viewer · Main offline Python application for loading, parsing, and browsing mailbox contents. · `mbox_viewer_streamlit.py`
- [HTML viewer](https://github.com/monapdx/mailbreak/blob/main/email-viewer.html): alternate viewer · Standalone browser-based email viewer for local inspection of messages. · `email-viewer.html`
- **Offline mode**: runtime boundary · Local-only execution with no backend, sync service, or remote persistence.

### Docs

Usage guidance and workflow documentation.

- [README](https://github.com/monapdx/mailbreak/blob/main/README.md): usage guide · Primary written overview of the workflow and project purpose. · `README.md`
- [Instructions](https://github.com/monapdx/mailbreak/blob/main/MailBreak-Instructions.pdf): workflow guide · Detailed operating instructions for preparing and browsing exported mail. · `MailBreak-Instructions.pdf`

## Connections

- 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.
