rustybeds/wiki/10-modernization-roadmap.md

Modernization Roadmap

Purpose

This document defines how BEDS transitions from proof-of-concept broker plumbing to a modern, production-grade platform.

This is not a strict PHP feature port checklist. The objective is to preserve architectural strengths while replacing legacy mechanisms where better patterns now exist.

Product Direction

• BEDS is a product rewrite in Rust, not a language translation exercise.
• AMQP-first remains a core invariant.
• Service role is config-driven from one binary.
• The white-paper target is a Twitter-like backend showcase (SPEW) launched by configuration and template/domain declarations, with zero core framework code changes.

Current Program Mode

The project is currently in POC-first mode.

Immediate objective:

• Stand up two brokers (rBroker and wBroker)
• Attach them to AMQP service
• Prove message flow and broker replies

Guardrails are intentionally deferred until POC behavior is stable.

Must-Keep Invariants

1. AMQP-first data path for application operations.
2. Config-driven role selection (appServer, admin, segundo, tercero).
3. Template-driven domain onboarding.
4. Database-agnostic broker and factory boundaries.
5. DBA-owned schema boundary (no ad hoc query logic in app layer).

Modernization Requirements (First Pass)

Message Contracts

1. Define versioned request and response envelopes.
2. Standardize correlation and causation identifiers.
3. Validate payload shape at broker ingress with deterministic error responses.

Reliability Semantics

1. Define explicit ack and nack policy per error class.
2. Add retry strategy and dead-letter queue handling.
3. Add idempotency strategy for mutating operations.

Broker Runtime

1. Add supervised broker lifecycle (respawn failed tasks).
2. Add graceful shutdown and queue drain behavior.
3. Add health states and readiness semantics.

Configuration System

1. Add schema-level config validation at startup.
2. Add explicit config versioning and migration path.
3. Define environment and secret handling policy.

Factory and Templates

1. Build typed template registry and dispatch.
2. Separate template metadata from adapter execution logic.
3. Preserve template capability toggles (audit, journal, locking, cache, retention).

Observability and Lineage

1. Keep and formalize event lineage fields.
2. Add structured telemetry for queue lag, throughput, retries, and latency distributions.
3. Provide operator-facing diagnostics for stuck consumers and poison messages.

Security Baseline

1. Enforce authenticated producer and consumer connectivity.
2. Define service-origin trust checks for internal events.
3. Centralize authorization for template access boundaries.

Data and Cache Behavior

1. Define cache invalidation contracts for write events.
2. Define read consistency options per template.
3. Add optimistic concurrency where needed.

Verification and Testing

1. Add message-contract compatibility tests.
2. Keep integration tests with real RabbitMQ in CI where possible.
3. Add failure-path and soak test milestones before code-complete.

Execution Sequence

Phase A: POC Transport Stability (Now)

Goal:

• Prove broker startup and message flow for rec.read and rec.write.

Definition of done:

• Spawn tests pass.
• Message round-trip smoke tests pass.
• Wiki reflects current tested behavior.

Phase B: Minimal Core Dispatch

Goal:

• Replace handler stubs with basic factory wiring for one template path.

Definition of done:

• fetch and write events route through a real dispatch path.
• End-to-end request and response schema is stable for first template.

Phase C: Guardrail Install

Goal:

• Add reliability and validation layers without breaking proven POC behavior.

Definition of done:

• Deterministic ingress validation.
• Explicit ack/nack behavior.
• Basic dead-letter and retry policy in place.

Phase D: Productization Baseline

Goal:

• Hardening for repeatable deployment and operations.

Definition of done:

• Supervision and graceful shutdown.
• Operator diagnostics and telemetry.
• Config schema and migration strategy.

Phase E: White-Paper Readiness

Goal:

• Demonstrate zero core code changes for new product behavior.

Definition of done:

• SPEW backend behavior enabled through config and template/domain declarations.
• Benchmark and lineage evidence captured for white-paper material.

Acceptance Gates

1. Functionality gate: broker flow and dispatch correctness.
2. Reliability gate: bounded behavior under failures.
3. Operability gate: observable and diagnosable runtime.
4. Product gate: new domain behavior without core edits.

Documentation Rule

Any substantive architecture or runtime behavior change must update relevant wiki pages in the same change set.