plba/requirements/vision.md

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