plba/requirements/architecture.md

Architecture

Overview

PLBA consists of four logical layers:

• platform core
• platform contracts
• infrastructure services
• business applications

The runtime is centered on Worker.

Layers

Platform core

Core services:

• RuntimeManager
• ConfigurationManager
• WorkerSupervisor
• ServiceContainer

Responsibilities:

• bootstrap runtime
• wire core services
• register modules
• start and stop workers
• expose runtime snapshot

Platform contracts

Main contracts:

• ApplicationModule
• Worker
• ConfigProvider
• HealthContributor
• tracing contracts

These contracts must remain domain-agnostic.

Infrastructure services

Platform services include:

• tracing
• health registry
• logging manager
• control plane
• config providers
• InMemoryTaskQueue as optional utility

Business applications

Applications define:

• routines
• domain services
• custom worker implementations
• typed app config

Runtime flow

1. runtime starts
2. configuration is loaded
3. core services become available
4. application modules register workers
5. workers start execution
6. workers call business routines
7. runtime aggregates health and status
8. runtime stops workers on request

Worker model

Worker is responsible for runtime behavior:

• execution strategy
• thread ownership
• graceful shutdown
• runtime status
• health interpretation

Routine is responsible for business behavior:

• business decisions
• domain orchestration
• persistence and integrations

Recommended shape:

class SomeWorker(Worker):
    def __init__(self, routine) -> None:
        self._routine = routine

    def start(self) -> None:
        ...

    def stop(self, force: bool = False) -> None:
        ...

    def health(self) -> WorkerHealth:
        ...

    def status(self) -> WorkerStatus:
        ...

Design rules

1. Runtime should not know business semantics

PLBA knows:

• worker started
• worker stopped
• routine succeeded
• routine failed

PLBA does not know:

• what the business operation means
• which domain decision was made

2. Queue is not a core architecture primitive

Queues may exist inside applications as implementation details.

They must not define the platform mental model.

3. Keep components small

Prefer:

• thin workers
• focused routines
• dedicated domain services

Avoid large platform abstractions that exist only for hypothetical reuse.