Draft Architectural Design Rationales

I will keep track of important design decisions in here.

🧭 High-Level Structure

1. Workflow Layering

   • Main.xaml: handles framework integration, not business logic.
   • Process.xaml: central control for retries, error handling, logging.
   • Modules: functional building blocks invoked by Process.xaml.
   • Units-of-Work: fine-grained, testable workflows.

⚙️ Parameter Interface Strategy

2. Shared Complex Object Passing

   • Decision: Pass shared context (e.g., JObject, TransactionItem, Dictionary) from Process.xaml to modules.
   • Driver: Centralize context; avoid repeated deserialization.

3. Flat Arguments in Units-of-Work

   • Decision: Use flat In_ arguments in low-level workflows.
   • Driver: Facilitate unit testing and signature clarity.

🧱 Data Marshalling Strategy

4. JObject at Entrypoint

   • Decision: Accept JObject as input from Orchestrator/Maestro.
   • Driver: Matches external JSON payload directly.

5. Deferred Marshalling

   • Observation: Conversion to structured formats happens inconsistently across layers.
   • Open Question: Where should marshalling to DTOs or dictionaries occur?

💻 Implementation Flexibility

6. Low Initial Barrier to Use Coded Source Files

   • Decision: Allow integration of .vb or .xaml class definitions or helper files.
   • Driver: Enable typed DTOs, validation helpers, or shared constants without heavy refactoring.

7. Use of Global Variables for Exception Data

   • Decision: Use global Workflow variables to transfer information from Global Handler to Main.xaml output.
   • Driver: Preserve error context for orchestrator or BPMN-level consumers.

8. Linear Entrypoint Flow (No TransactionItem Loop)

   • Decision: Main.xaml executes a linear process, not REFramework-style looping.
   • Driver: Align with Maestro task model (one payload → one response), not queue-based repetition.

---

Appendix

ADR Status Values

Status	Meaning
Proposed	The decision has been suggested but not yet agreed upon.
Accepted	The team has agreed to adopt this decision.
Superseded	This decision has been replaced by a newer ADR.
Deprecated	This decision is no longer recommended for use but may still be in effect.
Rejected	The decision was considered but not adopted.
Obsolete	The decision is no longer relevant due to architectural or business changes.
Amended	The decision was modified after acceptance. Optional; not always used.