# 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