plba/requirements/Mail Order Bot Migration Plan.md

Mail Order Bot Migration Plan

Purpose

This document describes how mail_order_bot will be adapted to the new runtime as the first pilot business application.

Scope

This is not a full migration specification for all future applications. It is a practical first use case to validate the runtime architecture.

Current model

The current application flow is tightly coupled:

• the manager checks IMAP
• unread emails are fetched
• emails are processed synchronously
• messages are marked as read after processing

Polling and processing happen in one execution path.

Target model

The new runtime-based flow should be:

1. a mail source detects new tasks
2. tasks are published to a queue
3. workers consume tasks in parallel
4. a domain handler processes each email
5. successful tasks lead to mark_as_read
6. failed tasks remain retriable

Phase 1

Source

• IMAP polling source

Queue

• in-memory task queue

Workers

• 2 to 4 parallel workers initially

Handler

• domain email processing handler built around the current processing logic

Delivery semantics

• email is marked as read only after successful processing
• unread state acts as the first safety mechanism against message loss

Why in-memory queue is acceptable at first

For the first phase:

• infrastructure complexity stays low
• the runtime contracts can be tested quickly
• unread emails in IMAP provide a simple recovery path after crashes

This allows us to validate the runtime architecture before adopting an external broker.

Phase 2

Replace:

• IMAP polling source

With:

• IMAP IDLE source

The queue, workers, and handler should remain unchanged.

This is an explicit architectural goal: source replacement without redesigning the processing pipeline.

Domain responsibilities that remain inside mail_order_bot

The runtime should not own:

• email parsing rules
• client resolution logic
• attachment processing rules
• order creation logic
• client-specific behavior

These remain in the business application.

Platform responsibilities used by mail_order_bot

The new runtime should provide:

• lifecycle
• configuration
• queue abstraction
• worker orchestration
• tracing
• health checks
• status/control APIs

Migration boundaries

Move into runtime

• source orchestration
• worker supervision
• queue management
• trace provisioning
• health aggregation

Keep in mail_order_bot

• email business handler
• mail domain services
• business pipeline
• business-specific config validation beyond platform-level schema

Success criteria

The migration is successful when:

• mail polling is no longer tightly coupled to processing
• workers can process emails in parallel
• business logic is not moved into the runtime
• replacing polling with IDLE is localized to the source layer