120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# Vision
|
|
|
|
## Purpose
|
|
|
|
This project provides a reusable runtime platform for business applications.
|
|
|
|
The runtime exists to solve service and infrastructure concerns that are needed by many applications but do not belong to business logic:
|
|
- start and stop
|
|
- status and lifecycle
|
|
- configuration
|
|
- worker execution
|
|
- trace propagation
|
|
- health checks
|
|
- control and administration
|
|
- later authentication and user management
|
|
|
|
The runtime should allow a business application to focus only on domain behavior.
|
|
|
|
## Vision statement
|
|
|
|
We build a platform where business applications are assembled from small domain modules, while the runtime consistently provides lifecycle, workers, tracing, configuration, and control-plane capabilities.
|
|
|
|
## Problem
|
|
|
|
In the previous generation, the execution model was centered around a single `execute()` entry point called by a timer loop.
|
|
|
|
That model works for simple periodic jobs, but it becomes too narrow when we need:
|
|
- queue-driven processing
|
|
- multiple concurrent workers
|
|
- independent task sources
|
|
- richer health semantics
|
|
- trace propagation across producer and consumer boundaries
|
|
- reusable runtime patterns across different applications
|
|
- future admin and authentication capabilities
|
|
|
|
The old model couples orchestration and execution too tightly.
|
|
|
|
## Desired future state
|
|
|
|
The new runtime should provide:
|
|
- a reusable lifecycle and orchestration core
|
|
- a clean contract for business applications
|
|
- support for sources, queues, workers, and handlers
|
|
- explicit separation between platform and domain
|
|
- trace and health as first-class platform services
|
|
- the ability to evolve into an admin platform
|
|
|
|
## Design principles
|
|
|
|
### 1. Platform vs domain separation
|
|
|
|
The runtime owns platform concerns.
|
|
Applications own domain concerns.
|
|
|
|
The runtime must not contain business rules such as:
|
|
- email parsing policies
|
|
- order creation logic
|
|
- invoice decisions
|
|
- client-specific rules
|
|
|
|
### 2. Composition over inheritance
|
|
|
|
Applications should be composed by registering modules and services in the runtime, not by inheriting a timer-driven class and overriding one method.
|
|
|
|
### 3. Explicit task model
|
|
|
|
Applications should model processing as:
|
|
- task source
|
|
- task queue
|
|
- worker
|
|
- handler
|
|
|
|
This is more scalable than one monolithic execute loop.
|
|
|
|
### 4. Parallelism as a first-class concern
|
|
|
|
The runtime should supervise worker pools and concurrency safely instead of leaving this to ad hoc application code.
|
|
|
|
### 5. Observability by default
|
|
|
|
Trace, logs, metrics, and health should be available as platform services from the start.
|
|
|
|
### 6. Evolvability
|
|
|
|
The runtime should be able to support:
|
|
- different queue backends
|
|
- different task sources
|
|
- different control planes
|
|
- different admin capabilities
|
|
without forcing business applications to change their domain code.
|
|
|
|
## First target use case
|
|
|
|
The first business application is `mail_order_bot`.
|
|
|
|
Its business domain is:
|
|
- fetching incoming mail
|
|
- processing attachments
|
|
- executing order-related pipelines
|
|
|
|
Its platform/runtime needs are:
|
|
- lifecycle management
|
|
- polling or IMAP IDLE source
|
|
- queueing
|
|
- worker pools
|
|
- tracing
|
|
- health checks
|
|
- future admin API
|
|
|
|
This makes it a good pilot for the new runtime.
|
|
|
|
## Success criteria
|
|
|
|
We consider the runtime direction successful if:
|
|
- `mail_order_bot` business logic can run on top of it without leaking infrastructure details into domain code
|
|
- the runtime can manage concurrent workers
|
|
- the runtime can support a queue-based flow
|
|
- the runtime can expose status and health
|
|
- the runtime can later host admin/auth features without redesigning the core
|