plba/requirements/README.md

PLBA Requirements

Goal

PLBA is a reusable runtime for business applications.

The platform owns:

• lifecycle
• worker orchestration
• configuration loading
• logging configuration
• health aggregation
• tracing
• control endpoints

Business applications own:

• business workflows
• domain services
• app-specific configuration schema
• business error semantics

Core runtime model

The platform is built around workers.

1. application defines an ApplicationModule
2. module registers workers
3. runtime starts workers
4. workers execute business activity
5. runtime aggregates status and health
6. runtime stops workers gracefully

Contracts

ApplicationModule

Responsibilities:

• provide module name
• assemble application components
• register workers
• register optional health contributors

Worker

Main runtime contract.

Responsibilities:

• start()
• stop(force=False)
• health()
• status()

The worker owns execution mechanics:

• single-run or loop
• thread model
• stop conditions
• runtime status
• health interpretation

Routine

Routine is an application pattern, not a PLBA contract.

Responsibilities:

• execute business behavior
• call domain services
• apply business rules
• talk to external integrations

Recommended rule:

• worker orchestrates
• routine executes business behavior

Architectural rules

1. Keep lifecycle and business behavior separate

Good:

• worker manages threading, loop, stop flags, health, status
• routine contains business logic

Bad:

• worker mixes thread management, retry policy, parsing, persistence, integration rules, and domain decisions in one class

2. Treat Worker as the main extension point

Do not center the platform around queues, handlers, sources, or other specialized runtime categories.

3. Keep Routine out of the platform contract set

At the current stage PLBA should not force a universal Routine interface.

Applications may use:

• run()
• run_once()
• poll()
• sync_window()

The exact business API belongs to the application.

4. Health is computed by the worker

Routine should not directly mutate platform health state.

Instead:

• routine succeeds
• routine returns outcome
• or routine raises typed exceptions

Worker interprets the outcome into:

• ok
• degraded
• unhealthy

5. InMemoryTaskQueue is utility-only

InMemoryTaskQueue may stay as a reusable component for business applications.

It is:

• optional
• local
• not part of the main runtime contract model

Public package direction

Public namespace plba should expose:

• application/runtime contracts
• tracing
• health
• config
• control plane
• utility queue

It should not expose queue-centric runtime abstractions as primary architecture.