Design Principles

MDWR is built on six core design principles that guide every aspect of the system.

1. Workflow-First API

Workflows are the primary abstraction. Developers think in terms of workflows, not infrastructure.

// Simple, intuitive API
const workflow = Workflow.create("my_workflow")
  .step("step1", handler1, true)
  .step("step2", handler2, true);

2. Explainability by Default

Every decision must be explainable. This is enforced at compile-time (TypeScript) or runtime (Python).

// Required structure
return {
  decision: "approve",
  reason: "High LTV customer and refund under threshold",
  confidence: 0.87
};

3. Memory is Implicit, Not Optional

Memory is always available. No configuration needed for basic usage.

// Memory is always there
const insights = await ctx.memory.similar({
  situation: "my_decision",
  context: ctx.input
});

4. Identical Behavior Across Languages

TypeScript and Python SDKs produce identical behavior. Same workflows, same results.

// TypeScript
const workflow = Workflow.create("refund_v1")
  .step("evaluate", handler, true);

# Python - same behavior
workflow = Workflow.create("refund_v1")
@workflow.step("evaluate", decision_required=True)
async def evaluate(ctx):
    # ...

5. Zero-Config Onboarding

Get started in minutes. No infrastructure setup required.

# That's it!
npx mdwr init
npx ts-node scripts/deploy.ts

6. Safe Evolution via Replay

Test changes safely with replay modes.

// Test policy changes
const replayed = await execution.replay({
  mode: "policy-aware",
  overrides: { policyVersion: "v2" }
});

Implications

These principles ensure:

Next Steps