plba/requirements/application_guidelines.md

Application Guidelines

Purpose

This document defines the default rules for building business applications on top of plba.

The goal is to keep applications:

• explicit
• small
• easy to debug
• free from platform legacy artifacts

Main model

Build every application around this chain:

ApplicationModule -> Worker -> business Routine

Meaning:

• ApplicationModule assembles the application
• Worker owns runtime execution and lifecycle
• Routine owns business behavior

Routine is an application pattern, not a mandatory platform contract.

Rules

1. Assemble the app in ApplicationModule

ApplicationModule should:

• create application services
• create routines
• create workers
• register workers
• register optional health contributors

ApplicationModule should not:

• execute business logic itself
• contain runtime loops

2. Treat Worker as the only primary runtime abstraction

Worker is the core runtime contract of the platform.

Worker should own:

• start()
• stop(force=False)
• health()
• status()
• thread ownership
• execution strategy
• graceful shutdown

Worker should not own:

• large business flows
• domain decisions
• parsing, persistence, and integration rules all mixed together

3. Keep one worker focused on one business activity

Default recommendation:

• one worker -> one routine

If a process has multiple distinct behaviors:

• split it into multiple workers
• or compose several services behind one focused routine

Do not make a worker a container for unrelated business scenarios.

4. Put business logic into routines and services

Routine should contain:

• business flow steps
• domain service calls
• business validation
• integration calls
• persistence orchestration

If the routine becomes too large:

• split business logic into dedicated services
• keep routine as a thin application-level orchestrator

5. Let the worker define the run model

The worker decides:

• single-run or loop
• one thread or multiple threads
• interval between iterations
• batch or long-running mode
• stop conditions

The routine does not decide lifecycle strategy.

6. Let the worker compute health

Routine should not directly set platform health state.

Instead:

• routine completes successfully
• or returns outcome information
• or raises typed exceptions

Then worker interprets that into:

• ok
• degraded
• unhealthy

7. Use queues only as optional app-level utilities

InMemoryTaskQueue may be used inside an application when buffering helps.

But:

• queue is not a core platform concept
• queue usage should stay a local implementation choice
• the app should still be described through workers and routines

8. Keep tracing vocabulary neutral

Use tracing to describe operations and execution context, not legacy architectural roles.

Prefer terms like:

• operation
• worker
• routine
• metadata
• step

Avoid making trace terminology define the application architecture.

9. Keep classes small and responsibilities clear

Preferred shape:

• thin ApplicationModule
• thin Worker
• focused Routine
• dedicated domain services

If a class grows too much, split it by responsibility instead of adding more platform abstractions.

Checklist

Before adding a new application component, check:

1. Is this runtime behavior or business behavior?
2. If runtime behavior, should it live in a Worker?
3. If business behavior, should it live in a Routine or service?
4. Does this component stay small and single-purpose?
5. Am I adding a queue because it is useful, or because of old mental models?