Overall Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• crates/mailiner-app/src/lib.rs
• crates/mailiner-composer/src/lib.rs
• crates/mailiner-imap-connector/src/lib.rs
• crates/mailiner-mime/src/writer/mod.rs
• crates/mailiner-app/src/formatter/html.rs

Mailiner is a browser-based IMAP client written in Rust that compiles to WebAssembly (WASM). It functions as a fat client, performing encryption and email processing directly in the user's browser rather than relying on an intermediate application server.

The system bypasses browser TCP limitations by routing encrypted IMAP traffic through a WebSocket-to-TCP proxy. This ensures that the proxy provider cannot view the content of communications, as the TLS handshake occurs within the client.

Sources: README.md:1-26, AGENTS.md:5-10

System Components

The project consists of several specialized crates that handle the frontend UI, protocol connectors, and message processing.

Component	Responsibility
mailiner-app	Dioxus-based UI and WASM entry point.
mailiner-core	Core data models and connector traits.
mailiner-imap-connector	IMAP protocol implementation and session management.
mailiner-composer	Email drafting, rich text editing, and pre-send orchestration.
mailiner-mime	RFC 5322 serialization and MIME structure writing.
mailiner-html	Shared HTML/CSS sanitization for viewer and composer.

Sources: crates/mailiner-composer/src/lib.rs:11-20, crates/mailiner-app/Cargo.toml:17-40

Connection and Proxy Flow

Mailiner uses a WebSocket connection to communicate with a remote IMAP server. The ws-tcp-proxy forwards payloads between the client's WebSocket and the server's TCP port.

The diagram shows the network path from the browser-resident WASM client to the destination IMAP server.
Sources: README.md:12-23

Data Flow and Protocol Handling

IMAP Connector Logic

The ImapConnector manages the state of the IMAP session, transitioning through Disconnected, Unauthenticated, and Authenticated states. It implements the EmailConnector trait to provide standardized access to folders and messages.

• Session Management: Uses an Arc<Mutex<ImapSession>> to share the connection state safely.
• Caching: Maintains a structure_cache for BODYSTRUCTURE data to improve performance.
• Streaming: Implements stream_raw_part using progressive partial FETCH commands to minimize memory usage during large attachment downloads.

Sources: crates/mailiner-imap-connector/src/lib.rs:88-106, crates/mailiner-imap-connector/src/lib.rs:727-770

Message Formatting and Security

The application enforces strict security policies when rendering HTML emails. The MessageFormatter utilizes ammonia and custom regex filters to prevent XSS and protect user privacy.

• Resource Blocking: Strips remote images and CSS url() references by default.
• CID Resolution: Rehydrates cid: URIs into local data: URLs using message parts.
• Shadow DOM: Mounts sanitized HTML inside a shadow root to isolate styles from the main UI.

Sources: crates/mailiner-app/src/formatter/html.rs:44-90, crates/mailiner-app/src/formatter/mod.rs:20-25

Email Composition and Export

The mailiner-composer crate handles the lifecycle of an email draft. It orchestrates the transition from a UI model to a raw MIME message.

The sequence shows the process of converting a user-edited draft into a serialized message ready for transmission.
Sources: crates/mailiner-composer/src/lib.rs:11-20, crates/mailiner-composer/src/export.rs:52-100

MIME Serialization

The mailiner-mime crate implements RFC 5322 writing. It handles:

1. Header Folding: Ensures headers stay within the 78-character limit.
2. Character Encoding: Uses RFC 2047 "Q" encoding for non-ASCII subjects and display names.
3. Multipart Construction: Generates boundaries and nests alternative, related, and mixed parts.

Sources: crates/mailiner-mime/src/writer/mod.rs:53-76, crates/mailiner-mime/src/writer/mod.rs:222-243

Security Configuration (CSP)

Mailiner implements a baseline Content-Security-Policy via meta tags to harden the application against XSS.

Directive	Value	Purpose
script-src	'self' 'wasm-unsafe-eval'	Restricts execution to local WASM.
style-src	'self' 'unsafe-inline'	Allows Dioxus inline styles for layout.
img-src	'self' data: blob: http: https:	Supports inlined images and user-allowed remote content.
object-src	'none'	Disables dangerous plugins.

Sources: README.md:38-55

Conclusion

Mailiner's architecture prioritizes a local-first, privacy-centric approach by moving the entire email logic into the browser via Rust and WASM. By utilizing a simple proxy only for protocol translation and implementing robust sanitization and serialization within the client, it provides a secure web-based alternative to traditional desktop email clients.