# 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