Workflow Details

Start with your business domain, not technology choices. RIDDL's language is designed for the concepts that Solutions Architects and Enterprise Architects think in: domains, bounded contexts, entities, commands, events, and workflows.

Instead of jumping to microservice diagrams or database schemas, you describe what the system does and how it behaves. Business stakeholders can read and review the specification directly — no translation layer, no UML ambiguity.

The AI assistant can help here: describe your domain in plain English, and it will suggest an initial RIDDL structure using proven patterns from our template library.

Further reading: Introduction to RIDDL · Language Reference

Don't start from scratch. The riddl-models library provides industry-specific starting points organized by vertical: healthcare, finance, commerce, and more.

Each template encodes real-world domain patterns — patient management workflows, payment processing pipelines, inventory systems — that you customize for your specific needs rather than reinventing from first principles.

Or start with a blank canvas. The RIDDL Playground lets you experiment with the language right in your browser, with bundled examples to learn from.

Further reading: riddl-models on GitHub · riddl-examples on GitHub

Synapify is a visual editor that makes RIDDL modeling accessible to architects, domain experts, and developers alike. Drag and drop domains, contexts, entities, and workflows in a visual canvas, or write RIDDL directly in the integrated text editor — changes sync bidirectionally.

Validation runs as you type, using the exact same engine as the riddlc compiler. Structural errors, missing definitions, and semantic issues surface immediately — not days later in code review.

The AI assistant is embedded in Synapify, offering pattern suggestions, error explanations, and completeness checks as you refine the model. Ask it to expand a pattern, suggest what to add next, or explain why a validation rule failed.

Further reading: Synapify product page · RIDDL Compiler · EBNF Grammar

Synapify creates a digital twin of your RIDDL model — a running simulation that exercises every entity, message flow, and state machine without a single line of implementation code. The RIDDL model is the spec, the digital twin is the simulation, and Synapify is the control plane where you observe results and steer the next iteration.

Simulation validates behavior, not just structure. Does the entity handle this command sequence correctly? Do state transitions fire the right events? Do cross-context workflows complete as expected? Find design flaws when they cost minutes to fix, not weeks.

Five Simulation Layers

Each layer is opt-in with sensible defaults. Start simple and add layers as your design matures:

1. System Model — Exercises entity state machines, command handlers, and message flows as defined in the model. Entity state machine tests auto-generate from the specification.
2. Timing — Models realistic latency differences between fast intra-context messaging and slower cross-context network hops. Configurable profiles reveal timing-sensitive design issues.
3. Chaos — Injects failures: dropped messages, timeouts, partial outages. Tests resilience before production does it for you.
4. Infrastructure — Models hardware as general classes (compute, storage, networking) to validate capacity and persistence assumptions.
5. Cost — Estimates cloud resource consumption from simulated load, catching expensive design decisions at the whiteboard stage.

Scenario-Driven

Epics already in your RIDDL model drive simulation scenarios. You don’t re-describe your flows — you orchestrate instances: how many users, what timing, what mix of journeys. AI reads your model and intentions to author realistic scenarios including edge cases you might not write by hand.

When simulation reveals issues, revise the model in Synapify and re-simulate — an iterative cycle that converges on a design you can trust before committing to implementation.

Your RIDDL specification is your documentation. The compiler generates comprehensive documentation sites directly from the model, including domain maps, entity catalogs, message flow diagrams, and glossaries — all hyperlinked and searchable.

Because the docs are generated from the same source as the code, they never go stale. Every regeneration reflects the current state of the domain model. Descriptions, annotations, and comments written in the RIDDL source flow through to the documentation automatically.

This is one of RIDDL's existing capabilities — the riddlc compiler already produces Hugo-compatible documentation sites from validated models.

Further reading: RIDDL Compiler · Introduction to RIDDL

Transform your validated, simulation-tested model into implementation scaffolding. The code generator produces entity classes, command handlers, event definitions, message types, API endpoints, and test stubs — all derived directly from the RIDDL specification.

Generated code preserves the structure and naming of your domain model. Developers implement business logic in clearly-marked placeholders rather than wiring up boilerplate. The model remains the source of truth — regenerate after model changes without losing hand-written logic.

AI assistance is particularly valuable here: the MCP server helps interpret RIDDL specifications for target-language idioms, generating natural Scala or Java code that follows framework conventions.

From Generated Code to Production

Generated code integrates with your existing build tools, CI/CD pipelines, and deployment infrastructure. Developers focus on implementing business logic in the generated placeholders, then compile, run tests, and deploy using their standard toolchain.

If tests reveal issues that trace back to the domain model — a missing state transition, an under-specified workflow, a command that doesn't produce the right events — loop back to Synapify to correct the model, re-simulate, regenerate, and retest.

The RIDDL specification continues to serve as living documentation after deployment. When requirements change, update the model first, validate the change, and regenerate — the specification evolves with the system rather than decaying into outdated diagrams.