# RUAL Documentation

> Documentation for RUAL, a platform where web applications are built from blueprints: visual flows of connected blocks that run on a cluster. Pages, REST APIs, storage, scheduled work and background queues are all built on the same canvas, without writing backend code.

Key facts:

- Product: RUAL, a visual application platform. Blueprints are edited in RUAL Studio (https://rual.at) and run on a customer cluster.
- Maker: Deverence Group B.V. (https://rual.nl).
- Building blocks: over 1000 blocks across groups such as storage, query, mutations, state ui, http connection, files, redis, locking and events.
- Storage: JSON documents, schema-less, full-text search, no relationships between documents. Every document carries a `_meta` object with guid, timestamps and removal state.
- Updates: mutations are applied sequentially per document, so counters and array operations are safe without a lock. File actions have no such lock and need one explicitly.
- APIs: each cluster exposes 40+ built-in REST endpoints, and you can register your own endpoints from a blueprint and secure them with scopes.
- Releases: monthly core versions, one development release and one stable release at a time; production runs the latest stable.
- Access: clusters have no public sign-up. An administrator creates the account and hands out the cluster URL, username and password.

Every page below also exists as HTML (drop the .md suffix), and any page URL returns markdown when the request sends `Accept: text/markdown`.

## Getting started
- [Getting started](https://docs.rual.nl/index.md): what RUAL is and where to begin
- [Quickstart](https://docs.rual.nl/getting-started/quickstart.md): first blueprint in 15 minutes, a page and a JSON endpoint
- [Build Your First CRUD App](https://docs.rual.nl/getting-started/first-crud-app.md): create, list, update, delete and search documents
- [Core Concepts](https://docs.rual.nl/getting-started/core-concepts.md): blueprints, blocks, flows, storage, activation and deployment
- [Support](https://docs.rual.nl/support.md): the checks that solve most problems and what to include in a report

## Cluster
- [Cluster overview](https://docs.rual.nl/cluster.md): Everything around the cluster itself: getting an account, managing who may do what, and exposing your own REST endpoints.
- [Getting Access](https://docs.rual.nl/cluster/getting-access.md): How you receive a cluster URL, username and password, and what to do on first login.
- [User Access](https://docs.rual.nl/cluster/user-access-management.md): Create users, hand out scopes, reset access and read the activity trail.
- [User Roles Explained](https://docs.rual.nl/cluster/user-roles-explained.md): What each role may do, how authentication groups combine, and which scope covers which action.
- [Token Device Data](https://docs.rual.nl/cluster/user-token-info.md): What a token stores about the device and session, and how to read the token list.
- [Deployment Usage](https://docs.rual.nl/deployment/how-to-deploy.md): Move a saved blueprint to production and check what the deployment changed.
- [Build Your First API](https://docs.rual.nl/cluster/api-quickstart.md): Register a versioned GET endpoint, return JSON from storage, validate input and lock it behind a scope.
- [API Guide](https://docs.rual.nl/cluster/api-guide.md): How the cluster APIs are structured: authentication, versioning, paging and error shapes.
- [All Cluster APIs](https://docs.rual.nl/cluster/api.md): The generated reference for every built-in REST endpoint on your cluster.

## Blueprints
- [Blueprints overview](https://docs.rual.nl/blueprints.md): The visual programming model: how flows execute, how storage works, and the patterns that keep large blueprints readable.
- [Introduction](https://docs.rual.nl/blueprints/introduction.md): The canvas, blocks, pins and flow: creating a blueprint, connecting blocks, navigating the canvas and its menus, the vocabulary the rest of these pages assume.
- [Tips & tricks](https://docs.rual.nl/blueprints/tips-and-tricks.md): Navigate big blueprints, connect, select, group and copy blocks, stage and save, simulate functions, and use namespaces, block search and the minimap.
- [Best Practices](https://docs.rual.nl/blueprints/best-practices.md): Naming, namespaces, tags and structure that keep a blueprint maintainable: when to split one, reusable functions, performance and habits for teams.
- [Common Blueprint Patterns](https://docs.rual.nl/blueprints/common-patterns.md): Reusable blueprint shapes for form validation, API authentication, JSON API replies, mapping and transforming arrays, error handling and caching.
- [Block Execution](https://docs.rual.nl/blueprints/block-execution.md): The order blocks run in, how flow pins drive execution depth first, where values are resolved, precompiled data, error handling and debugging a run.
- [Object References and Copies](https://docs.rual.nl/blueprints/object-references.md): Objects are passed by reference: which blocks change the original, when to take a shallow or deep copy, and why storage documents follow the same rule.
- [Locking and Concurrency](https://docs.rual.nl/blueprints/locking.md): Document updates lock themselves, file actions do not. How and when to claim a lock yourself, and the pattern for safely updating a shared file.
- [Storages](https://docs.rual.nl/blueprints/storage.md): The JSON document model, _meta, transactional mutations and how to query documents: search queries, full-text search, expiry, removal and Redis caching.
- [Storage Events](https://docs.rual.nl/blueprints/storage-events.md): React to document creates and updates with storage events: the event payload, how rapid updates are combined, and how to keep flows out of write loops.
- [Storage Examples](https://docs.rual.nl/blueprints/storage-examples.md): Worked RUAL document designs for user profiles, product catalogs, order management and activity logs, plus how to shape documents for fast search.
- [Dates and Time Ranges](https://docs.rual.nl/blueprints/time-ranges.md): Dates are stored in seconds, three _meta fields are in milliseconds, and a filter in the wrong unit returns nothing without erroring.
- [Protected Storages](https://docs.rual.nl/blueprints/protected-storages.md): Keep a storage usable by a flow and by your users while its contents stay out of the studio: what protection withholds, who sees the data, how to turn it on.
- [Repeating Events](https://docs.rual.nl/blueprints/repeating-events.md): Schedule blueprint work on an interval and keep repeated runs from overlapping: the requirements, creating a repeating event, and why one may not run.
- [Queue](https://docs.rual.nl/blueprints/queue.md): Hand slow or bursty work to the RUAL queue and track what each task did: which jobs suit it, how to queue work, auto postpone, monitoring and analytics.
- [Assets](https://docs.rual.nl/blueprints/assets.md): Upload, manage and serve files, and reference them from a blueprint: public versus private assets, protected files, folders, formats, file sizes and video.
- [System Settings](https://docs.rual.nl/blueprints/system-settings.md): Read and write cluster-wide settings from a blueprint: central configuration such as email tokens and reply-to addresses, secured values and default keys.
- [System Settings Reference](https://docs.rual.nl/blueprints/system-settings-reference.md): Every predefined system setting, its type and what changing it affects, secure versus non-secure values, custom keys and reading settings in a blueprint.
- [Common Pitfalls](https://docs.rual.nl/blueprints/common-pitfalls.md): The blueprint mistakes that bite most often: trusting real-time search results, misusing aggregations, storage event write loops and silent no-ops.
- [Precompiling](https://docs.rual.nl/blueprints/precompiled.md): What a node's compiled copy of a blueprint holds, when a save rebuilds it, and what the green fast icon on a simulated value means.
- [Remote access control](https://docs.rual.nl/blueprints/remote-access-control.md): Scopes, the scopes modal, rate limits and throttles on your own endpoints: how public and private pages differ and how to secure a RUAL API endpoint.
- [Service Providers](https://docs.rual.nl/blueprints/service-providers.md): Credentials for external services, held by the cluster so a key never sits on a pin: setting a provider up, what it may be used for and rotating a key.
- [Places and Geo Search](https://docs.rual.nl/blueprints/places.md): Search the built-in places dataset, filter by proximity, category and typed filters, and enrich your own documents with it, plus the geo point helpers.

## Blueprint Language
- [Blueprint Language overview](https://docs.rual.nl/engine.md): Blueprint Language is the text form of a RUAL blueprint: edit it by hand, with an AI agent or in the Studio code view, and stage the change on the canvas.
- [Overview](https://docs.rual.nl/engine/overview.md): What Blueprint Language is, how its source relates to the canvas, and where to use it: the Studio code view and the source API.
- [Syntax](https://docs.rual.nl/engine/blueprint-language.md): Declarations, statements, expressions, block and storage calls, comments, the lock, // @xy positions and the checks a compile runs, with .blueprint examples.
- [Functions and Custom Pins](https://docs.rual.nl/engine/functions.md): Declare a function with arguments and returns in Blueprint Language, call it, also from another blueprint, and see its signature as custom pins on the canvas.
- [Editing with an AI Agent](https://docs.rual.nl/engine/editing-with-ai.md): Export, edit, dry run, stage and save: the public source API step by step, with the request and response of every step and the token scopes it needs.
- [Studio Code View](https://docs.rual.nl/engine/studio-code-view.md): The Canvas and Code switch in RUAL Studio: Check, Stage to canvas, Place unpositioned, the Positions toggle and what each message means.

## Interfaces
- [Interfaces overview](https://docs.rual.nl/interfaces.md): Building the front end in RUAL: RUAL Studio, the component libraries, custom components, and how to override the pages that ship by default.
- [Context Menu](https://docs.rual.nl/interfaces/contextmenu.md): The right-click menu on the canvas and the actions it can reach, such as modifying table columns and finding the blueprint block behind an element.
- [Components](https://docs.rual.nl/interfaces/components.md): How interface components are defined, configured and rendered: existing and custom components, blueprint parameters, triggering functions and React hooks.
- [RUAL Library](https://docs.rual.nl/interfaces/rual-library.md): The helper library available inside custom components through window.RUAL: how to use it, from runBlueprintFunction to every other function it offers.
- [RUAL Components](https://docs.rual.nl/interfaces/rual-components.md): The component set that ships with RUAL and the props each one takes: UIDs, translations, inputs, the commonly used components and how to style them.
- [RUAL Studio](https://docs.rual.nl/interfaces/rual-studio.md): The cluster management interface where blueprints, storages and users are managed: signing in, the dashboard, devices, cluster traffic and settings.
- [Handle Iterations](https://docs.rual.nl/interfaces/iterations.md): Render lists and repeat structures without fighting the renderer: when iterative components apply, the exposed iterate parameters and a worked example.
- [Overwrite Defaults](https://docs.rual.nl/interfaces/overwrite-default-pages.md): Replace the built-in login and system pages with your own: how overwriting works, which pages allow it, and tips for building a custom login page.
- [Login Escape Hatch](https://docs.rual.nl/interfaces/login-escape-hatch.md): Force the built-in login page with ?studio=1 when a custom login page locks you out: how it works, where it sits in page resolution and how to recover.

## Tutorials
- [Tutorials overview](https://docs.rual.nl/tutorials.md): End-to-end builds. Each tutorial starts from an empty blueprint and ends with something running: APIs, logins, dashboards, email, uploads and AI.
- [Building User Authentication](https://docs.rual.nl/tutorials/user-authentication.md): Build user authentication: the sign-in flow, login tokens, 2FA and the scope checks around them, gating pages and sections, and a hardening checklist.
- [Creating a REST API](https://docs.rual.nl/tutorials/rest-api.md): A complete CRUD REST API: list with filters, create with validation, read, update and delete, with paging, error replies, scopes and testing it.
- [Dashboard with Charts](https://docs.rual.nl/tutorials/dashboard-charts.md): Aggregate storage data and render it as a live dashboard with charts: get the data, render the page and keep it fast, with a checklist to finish on.
- [File Upload & Processing](https://docs.rual.nl/tutorials/file-upload-processing.md): Accept an upload from a page or an API, store it as an asset and process it safely in the background, with the safety rules every upload flow needs.
- [Email System Setup](https://docs.rual.nl/tutorials/email-system.md): Transactional email: sending from a flow, templates that survive edits, bulk and scheduled mail, delivery handling and the discipline behind deliverability.
- [Third-Party Integrations](https://docs.rual.nl/tutorials/third-party-integrations.md): Call external APIs, receive their webhooks, keep data in sync, keep credentials out of the canvas and handle failures with a few operational rules.
- [Building AI Endpoints](https://docs.rual.nl/tutorials/ai-endpoints.md): Add Claude to a blueprint: messages, structured JSON replies, streaming to the browser, classify and route, tools, cost control and batch jobs.
- [Building a Login Page](https://docs.rual.nl/tutorials/login-page.md): Passwordless login: email a code, verify it into a session token, and build the form page around it, with notes from running it in practice.
- [Building a Reporting API](https://docs.rual.nl/tutorials/reporting-api.md): A reporting API: aggregations over storage, answered as a CSV or XLSX download or sent as a scheduled email, with notes from running it in practice.
- [Handling City Filter Uploads](https://docs.rual.nl/tutorials/city-filter-uploads.md): Parse uploaded CSV or XLSX locations and keep only the rows inside your city or radius, then validate, enrich and store the rows that are left.
- [Building an API with Locking](https://docs.rual.nl/tutorials/api-locking.md): An API with locking: claim a lock around read-modify-write sections, keep the critical section small, and always release the lock again.
- [Local Home Automation](https://docs.rual.nl/tutorials/local-home-automation.md): Automate the building around a Nano: which radio to buy, the daemon stack, configuration, discovering and adopting devices, the blocks and a first flow.

## Home Automation
- [Home Automation overview](https://docs.rual.nl/home-automation.md): Run the building the node sits in: Zigbee, Thread/Matter, Z-Wave, Hue and Daikin devices in one vocabulary, automated by blueprints with no vendor cloud.
- [Introduction](https://docs.rual.nl/home-automation/introduction.md): What local home automation means here: the node as the gateway, one capability vocabulary across four radios, and what you need to own.
- [Setting Up a RUAL Nano](https://docs.rual.nl/home-automation/setting-up.md): The runbook: Redis, an MQTT broker, Zigbee2MQTT against a ZBT-2, the config section, first boot and proving the radio is connected.
- [Discovering and Adopting Devices](https://docs.rual.nl/home-automation/devices.md): Pairing per radio, why adoption is a separate gate, names and rooms, forget versus unpair, what survives a restart, and the device API.
- [Trigger Reference](https://docs.rual.nl/home-automation/triggers.md): All 28 start-of-flow device blocks and the three rules that decide how often they fire: transitions, threshold crossings and unknown-previous seeding.
- [Action Reference](https://docs.rual.nl/home-automation/actions.md): The 24 action blocks: lights, switches, climate, doors and gates, the generic capability write, the registry queries and fleet management.
- [Example Flows](https://docs.rual.nl/home-automation/example-flows.md): Nine complete automations, block by block: motion lights after dark, a leak shutting a valve, a house that empties itself, an unknown card at 3am.
- [Device History and Energy](https://docs.rual.nl/home-automation/history-and-energy.md): Why the node records what changed rather than what was said, buckets versus raw readings, meter deltas and the energy view.
- [Troubleshooting](https://docs.rual.nl/home-automation/troubleshooting.md): Symptom first: no devices, a trigger that will not fire, a door sensor that reads backwards, an empty chart, and the three checks that localise most faults.

## Examples
- [Examples overview](https://docs.rual.nl/examples.md): Reference applications. Each one shows the document design first, then the flows that read and write it: a blog, a shop, bookings, stock and tasks.
- [Simple Blog](https://docs.rual.nl/examples/simple-blog.md): A simple blog: the post document with slugs, tags and a published state, the public pages, the publishing flow and search, with takeaways to reuse.
- [E-Commerce Catalog](https://docs.rual.nl/examples/ecommerce-catalog.md): An e-commerce catalog: products with variants, stock and category filtering, the storefront, selling stock without double-selling, and the admin side.
- [User Management](https://docs.rual.nl/examples/user-management.md): User management: profiles alongside cluster users, the account lifecycle, teams and role changes, the admin pages and an audit trail of what changed.
- [Booking System](https://docs.rual.nl/examples/booking-system.md): A booking system: resources and time slots as documents, checking availability, conflict checks that prevent double-booking, and sending reminders.
- [Inventory Tracker](https://docs.rual.nl/examples/inventory-tracker.md): An inventory tracker: stock movements as an append-only log with derived levels, two ways to compute current stock, the flows and low-stock alerts.
- [Task Management](https://docs.rual.nl/examples/task-management.md): Task management: the task document with boards, columns, assignees and due dates, the views and flows around it, and notes on scaling it up.

## Reference
- [Reference overview](https://docs.rual.nl/reference.md): Lookup material. Short pages you come back to rather than read once: blocks, API endpoints, system settings, component props, error codes and more.
- [Block Quick Reference](https://docs.rual.nl/reference/block-quick-reference.md): The blocks you reach for daily, grouped by what they do: pages and UI, APIs and HTTP, storage and queries, data and logic, and background work.
- [API Endpoint Reference](https://docs.rual.nl/reference/api-endpoint-reference.md): Every cluster endpoint with its method, scope and reply shape: authentication, blueprints and blocks, users and access, storages, assets and logs.
- [System Settings Quick Ref](https://docs.rual.nl/reference/system-settings-quickref.md): System settings in one table, with defaults: locale and formats, language, dates and input, email and messaging, and your own custom keys.
- [Component Props Reference](https://docs.rual.nl/reference/component-props-reference.md): Props, types and defaults for the built-in components: universal props on every component, per-component props, styling and getting data in.
- [Error Code Reference](https://docs.rual.nl/reference/error-code-reference.md): What each error code means and what usually causes it: the error shape, 4xx caller errors, 5xx cluster errors, common error strings and blueprint errors.
- [Location Blocks](https://docs.rual.nl/reference/location-blocks.md): Offline geocoding, coordinate maths and points of interest: every geo point, places and map block in one place, with recipes and the datasets behind them.
- [DNS Zone Blocks](https://docs.rual.nl/reference/dns-blocks.md): Authoritative DNS from a storage: import from Route53, render a zone whole, check it on every nameserver, and push only what passed the gate.

## Architecture
- [Architecture overview](https://docs.rual.nl/architecture.md): Decisions you make once per project, and the reasoning behind them: which approach fits, versions and upgrades, Core Nano versus a cluster, and scaling.
- [Choosing Your Approach](https://docs.rual.nl/architecture/choosing-approaches.md): Blueprint, custom component or external service: which fits which problem, plus RUAL storage versus an external database and real-time versus polling.
- [Version Management](https://docs.rual.nl/architecture/version-guide.md): Release channels, a safe upgrade routine, where breaking changes and deprecations are documented, and which core version you should run.
- [RUAL Core Nano](https://docs.rual.nl/architecture/core-nano.md): The whole platform on one machine: SQLite instead of Elasticsearch, one box instead of a stack, and when to choose it over a cluster.
- [Scaling and Automatic Sizing](https://docs.rual.nl/architecture/scaling.md): How storage capacity is sized from what it holds, how many copies data keeps, what the nightly pass changes, and what stays a human decision.

## Troubleshooting
- [Troubleshooting overview](https://docs.rual.nl/troubleshooting.md): When something does not do what you expect, start here: common issues and their fixes, and how to debug a blueprint with the console and simulation.
- [Common Issues & Fixes](https://docs.rual.nl/troubleshooting/common-issues.md): Blueprints that do not save or respond, APIs that answer 404 or 401 after activation, UI that does not update, scope errors, slow flows and their fixes.
- [Debugging Blueprints](https://docs.rual.nl/troubleshooting/debugging.md): Debug a blueprint: the console, the simulation popup, error pins, production run versus the development view, the audit log and reading error messages.

## Blocks and releases
- [All blocks](https://docs.rual.nl/block-types.md): the block catalog, grouped by base group
- [Block Templates](https://docs.rual.nl/block-types/block-templates.md): copyable block combinations per use case
- [Finding Blocks](https://docs.rual.nl/block-types/finding-blocks.md): how to search the catalog
- [Core versions](https://docs.rual.nl/core-versions.md): release notes per version
- [Cluster APIs](https://docs.rual.nl/cluster/api.md): the generated REST reference

## Machine endpoints
- [Full documentation text](https://docs.rual.nl/llms-full.txt): every key page as one markdown document
- [Block catalog](https://docs.rual.nl/llms-blocks.txt): every non-deprecated block with pins, semantics and the blocks it is most often wired to
- [Sitemap](https://docs.rual.nl/sitemap.xml)
- [Release feed](https://docs.rual.nl/feed.xml): RSS of core releases
- [Search index](https://docs.rual.nl/search-index.json): pages, block groups and API categories as JSON
- Block summary as JSON: https://docs.rual.nl/blocks/<block_type>.json