135 lines
2.7 KiB
Markdown
135 lines
2.7 KiB
Markdown
# 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.
|