LambdaMail/docs/MAILBOX-CORE.md

Mailbox core

The webmail, IMAP, POP3 and SMTP are four ways in to one mailbox. They share the rules and the data code; none of them has its own copy.

Where each rule lives

Rule	One place
Flags, expunge, move, copy, folder delete, counters, quota	MailStore (services/protocols/internal/infrastructure/postgres/mail_store.go)
Folder and message reads	mail_store_read.go (same store)
Credentials (password, app password, scopes)	usecase/credentials.go
Sending, and the copy filed in Sent	ProcessOutboundEmail.Submit (FileSentCopy)
Default folders of a mailbox	SQL function provision_default_folders (migration 0014)

The IMAP repositories, the webmail repository and the TS auth service are thin adapters: they translate their protocol and call the code above.

Invariants

After any operation, through any port:

• folders.total_count and unread_count equal the live messages and the ones without \Seen.
• folders.highest_modseq rises only when a message really changed.
• mailboxes.used_bytes equals the size of the live messages.
• Deleting twice, or from two ports at once, counts once.

mail_state_contract_test.go checks all of this after every operation through the IMAP path and the webmail path, and under concurrency. e2e/one_mailbox_everywhere_e2e_test.go does the same over real SMTP, IMAP and HTTP on one mailbox.

Lock order

Every operation locks folders first, lowest id first, then the message (lockFolders). Two moves in opposite directions, or a move racing a flag change, used to deadlock (SQLSTATE 40P01) because they locked in different orders. TestContract_OppositeMovesAndFlagChangesNeverDeadlock covers it. A new operation must follow the same order.

Adding an operation

1. Put it in MailStore, in one transaction, with lockFolders.
2. Make the adapters call it.
3. Add it to the contract test and run it through both paths.

Migration 0014

Creates provision_default_folders, creates the missing default folders of existing mailboxes, and recomputes folder counters and used_bytes from the messages. It is idempotent and runs with the other migrations at deploy.

Not done

IMAP APPEND is still a stub. When it is implemented, drop a client-appended Sent copy that matches the server's one by Message-ID.