179 lines
6.3 KiB
Markdown
179 lines
6.3 KiB
Markdown
# 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.
|
|
|
|
## Historical Design Intent (Preserved)
|
|
|
|
These points come from operational experience in Namaste and are treated as architectural intent, not nostalgia.
|
|
|
|
1. Expensive resources should be long-lived:
|
|
- Logger transport clients, AMQP connections, and database clients should not be repeatedly instantiated for per-event semantic changes.
|
|
|
|
2. Template-derived operational state should live with runtime objects:
|
|
- The object that executes work should carry the template-derived state it needs for its full lifetime.
|
|
|
|
3. Public API contract must remain decoupled from internal schema:
|
|
- External developers interact with remapped/public field names and operation contracts.
|
|
- Internal table/collection names and DBO names remain private unless explicitly authorized.
|
|
|
|
4. Runtime template drift must be controlled:
|
|
- Running nodes should operate from a stable template snapshot for deterministic behavior.
|
|
- Template changes are applied through controlled reload/restart, not accidental file edits mid-run.
|
|
|
|
5. Template integrity is a future acceptance feature:
|
|
- Track per-template and registry-level fingerprints to detect drift and support cluster consistency checks.
|
|
|
|
6. Resource constraints are first-class requirements:
|
|
- BEDS must run on low-resource hardware (including RPi-class systems), so memory strategy must be intentional and bounded.
|
|
|
|
## 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.
|
|
|
|
Implementation status update:
|
|
- Phase A transport stability evidence exists: live RabbitMQ round-trip tests for `rec.read` and `rec.write` ping paths.
|
|
- Phase B has started: REC template registry loading and startup validation are now implemented in IPL.
|
|
|
|
## 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.
|