Правки описания

requirements/vision.md

@@ -0,0 +1,119 @@
+# 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