# charlierguo/gmail architecture

> Architecture diagram of the GitHub repository charlierguo/gmail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charlierguo/gmail
- Repository: https://github.com/charlierguo/gmail

## Overview

##### Project type and purpose
- This is a client-side Python library (“GMail for Python”) that wraps Google GMail’s functionality (search, read, send, label, archive, delete, etc.).
- It is not a full-stack application or service; it is an open-source tool intended to be embedded in other Python applications and scripts.

##### File structure
- Top-level files:
- README.md, LICENSE, setup.py – standard package metadata and installer
- gmail/ – the core Python package
- Within gmail/:
- gmail.py – the main `Gmail` client class (authentication, session management)
- mailbox.py – the `Mailbox` abstraction (inbox, labels, queries)
- message.py – the `Message` abstraction (headers, bodies, attachments, actions)
- utf.py, utils.py – helper modules (encoding, common utilities)
- exceptions.py – custom exception types (e.g. AuthenticationError)
- No frontend/UI; no database – the “backend” is the external Google GMail servers (IMAP/SMTP or HTTP API).
- setup.py indicates it’s installable via pip once packaged.

##### README for additional insights
- The library supports two authentication modes: simple username/password (IMAP login) and OAuth2.
- Exposes a fluent, object-oriented API:
- `Gmail.login(...)` → returns a session object
- `session.inbox().mail(...)` → returns a list of `Message` stubs
- `message.fetch()` → populates body, attachments, labels
- `message.read()/delete()/archive()/add_label()` → state-modifying calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application<br/>(User Code)"]:::client

    subgraph "Gmail Library"
        direction TB
        GmailClient["Gmail Client<br/>Session Management"]:::internal
        AuthService["Auth Service<br/>(IMAP & OAuth2)"]:::internal
        Mailbox["Mailbox Manager"]:::internal
        Message["Message Object"]:::internal
        Utils["Utils & Encoding Helpers"]:::internal
        Exceptions["Exception Handlers"]:::internal
        PackageInit["Package Initialization"]:::internal
    end

    subgraph "Standard Library Deps"
        direction TB
        StdImap["imaplib"]:::stdlib
        StdSmtp["smtplib"]:::stdlib
        StdHttp["httplib / urllib"]:::stdlib
        StdEmail["email / datetime"]:::stdlib
        StdFile["file I/O (open())"]:::stdlib
    end

    subgraph "External Services"
        direction TB
        OAuthServer["OAuth2 Auth Server"]:::external
        GmailServer["Google GMail API / IMAP/SMTP"]:::external
    end

    Client -->|"login() / authenticate()"| AuthService
    AuthService -->|"IMAP LOGIN"| StdImap
    AuthService -->|"OAuth2 Token Exchange"| OAuthServer
    AuthService -->|"HTTP Requests"| StdHttp
    AuthService -->|"session handle"| GmailClient

    GmailClient -->|"session.inbox().mail()"| Mailbox
    Mailbox -->|"IMAP SEARCH / HTTP GET"| GmailServer
    Mailbox -->|"message IDs"| Message

    Message -->|"fetch(): IMAP FETCH / HTTP GET"| GmailServer
    Message -->|"state actions: STORE/EXPUNGE / HTTP POST"| GmailServer
    Message -->|"stream attachments"| Utils
    Utils -->|"write to disk"| StdFile

    Client -->|"uses Message objects"| Message

    GmailClient -->|"raise errors"| Exceptions
    AuthService -->|"raise errors"| Exceptions
    Mailbox -->|"raise errors"| Exceptions
    Message -->|"raise errors"| Exceptions

    %% Click Events
    click GmailClient "https://github.com/charlierguo/gmail/blob/master/gmail/gmail.py"
    click AuthService "https://github.com/charlierguo/gmail/blob/master/gmail/gmail.py"
    click Mailbox "https://github.com/charlierguo/gmail/blob/master/gmail/mailbox.py"
    click Message "https://github.com/charlierguo/gmail/blob/master/gmail/message.py"
    click Utils "https://github.com/charlierguo/gmail/blob/master/gmail/utils.py"
    click Utils "https://github.com/charlierguo/gmail/blob/master/gmail/utf.py"
    click Exceptions "https://github.com/charlierguo/gmail/blob/master/gmail/exceptions.py"
    click PackageInit "https://github.com/charlierguo/gmail/blob/master/gmail/__init__.py"
    click setup "https://github.com/charlierguo/gmail/blob/master/setup.py"
    click README "https://github.com/charlierguo/gmail/blob/master/README.md"
    click LICENSE "https://github.com/charlierguo/gmail/tree/master/LICENSE"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#036,stroke-width:1px;
    classDef stdlib fill:#d9d9d9,stroke:#555,stroke-width:1px;
    classDef external fill:#d9ead3,stroke:#274e13,stroke-width:1px;
    classDef client fill:#fff2cc,stroke:#b58f00,stroke-width:1px;
```
