117 lines
2.8 KiB
Markdown
117 lines
2.8 KiB
Markdown
# 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
|