plba

Mail Order Bot Migration Plan.md

@@ -0,0 +1,116 @@
+# 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