112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
|
|
**`docs/adr/0001-new-runtime.md`**
|
|
```md
|
|
# ADR 0001: Create a new runtime project instead of evolving the legacy ConfigManager model
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The previous generation of the application runtime was centered around a timer-driven execution model:
|
|
- a manager loaded configuration
|
|
- a worker loop periodically called `execute()`
|
|
- applications placed most operational logic behind that entry point
|
|
|
|
That model is adequate for simple periodic jobs, but it does not match the direction of the new platform.
|
|
|
|
The new platform must support:
|
|
- task sources
|
|
- queue-driven processing
|
|
- multiple parallel workers
|
|
- trace propagation across producer/consumer boundaries
|
|
- richer lifecycle and status management
|
|
- health aggregation
|
|
- future admin web interface
|
|
- future authentication and user management
|
|
|
|
These are platform concerns, not business concerns.
|
|
|
|
We also want business applications to describe only business functionality and rely on the runtime for infrastructure behavior.
|
|
|
|
## Decision
|
|
|
|
We will create a new runtime project instead of implementing a `V3` directly inside the current legacy ConfigManager codebase.
|
|
|
|
The new runtime will be built around a platform-oriented model with explicit concepts such as:
|
|
- `RuntimeManager`
|
|
- `ApplicationModule`
|
|
- `TaskSource`
|
|
- `TaskQueue`
|
|
- `WorkerSupervisor`
|
|
- `TaskHandler`
|
|
- `TraceService`
|
|
- `HealthRegistry`
|
|
|
|
The old execute-centered model is treated as a previous-generation design and is not the architectural basis of the new runtime.
|
|
|
|
## Rationale
|
|
|
|
Creating a new runtime project gives us:
|
|
- freedom to design the correct abstractions from the start
|
|
- no pressure to preserve legacy contracts
|
|
- cleaner boundaries between platform and business logic
|
|
- simpler documentation and tests
|
|
- lower long-term complexity than mixing old and new models in one codebase
|
|
|
|
If we built this as `V3` inside the old project, we would likely inherit:
|
|
- compatibility constraints
|
|
- mixed abstractions
|
|
- transitional adapters
|
|
- conceptual confusion between periodic execution and event/queue processing
|
|
|
|
The expected long-term cost of such coupling is higher than creating a clean new runtime.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- the platform can be modeled cleanly
|
|
- business applications can integrate through explicit contracts
|
|
- new runtime capabilities can be added without legacy pressure
|
|
- mail_order_bot can become the first pilot application on the new runtime
|
|
|
|
### Negative
|
|
|
|
- some existing capabilities will need to be reintroduced in the new project
|
|
- there will be a temporary period with both legacy and new runtime lines
|
|
- migration requires explicit planning
|
|
|
|
## Initial migration target
|
|
|
|
The first application on the new runtime will be `mail_order_bot`.
|
|
|
|
Initial runtime design for that application:
|
|
- IMAP polling source
|
|
- in-memory queue
|
|
- parallel workers
|
|
- business handler for email processing
|
|
- message marked as read only after successful processing
|
|
|
|
Later:
|
|
- swap IMAP polling source for IMAP IDLE source
|
|
- keep the queue and worker model unchanged
|
|
|
|
## What we intentionally do not carry over
|
|
|
|
We do not keep the old architecture as the central organizing principle:
|
|
- no `execute()`-centric application model
|
|
- no timer-loop as the main abstraction
|
|
- no implicit mixing of lifecycle and business processing
|
|
|
|
## Follow-up
|
|
|
|
Next design work should define:
|
|
- core platform contracts
|
|
- package structure
|
|
- runtime lifecycle
|
|
- queue and worker interfaces
|
|
- config model split between platform and application
|
|
- pilot integration for `mail_order_bot`
|