# 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: the vocabulary the rest of these pages assume.
- [Tips & tricks](https://docs.rual.nl/blueprints/tips-and-tricks.md): Navigate big blueprints, group and copy blocks, and use the search menu efficiently.
- [Best Practices](https://docs.rual.nl/blueprints/best-practices.md): Naming, namespaces, tags and structure that keep a blueprint maintainable.
- [Common Blueprint Patterns](https://docs.rual.nl/blueprints/common-patterns.md): Reusable shapes for validation, mapping arrays, caching, error handling and API auth.
- [Block Execution](https://docs.rual.nl/blueprints/block-execution.md): The order blocks run in, how flow pins drive execution, and where values are resolved.
- [Object References and Copies](https://docs.rual.nl/blueprints/object-references.md): Objects are passed by reference: which blocks change the original, and when to take a shallow or deep copy.
- [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.
- [Storages](https://docs.rual.nl/blueprints/storage.md): The JSON document model, _meta, transactional mutations and how to query documents.
- [Storage Events](https://docs.rual.nl/blueprints/storage-events.md): React to document creates and updates, including how rapid updates are combined.
- [Storage Examples](https://docs.rual.nl/blueprints/storage-examples.md): Worked document designs for profiles, catalogs and orders.
- [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.
- [Repeating Events](https://docs.rual.nl/blueprints/repeating-events.md): Schedule work on an interval and keep repeated runs from overlapping.
- [Queue](https://docs.rual.nl/blueprints/queue.md): Hand slow or bursty work to the queue and track what each task did.
- [Assets](https://docs.rual.nl/blueprints/assets.md): Upload, manage and serve files, and reference them from a blueprint.
- [System Settings](https://docs.rual.nl/blueprints/system-settings.md): Read and write cluster-wide settings from a blueprint.
- [System Settings Reference](https://docs.rual.nl/blueprints/system-settings-reference.md): Every system setting, its type and what changing it affects.
- [Common Pitfalls](https://docs.rual.nl/blueprints/common-pitfalls.md): The mistakes that bite most often: caching, aggregations and silent no-ops.
- [Precompiling](https://docs.rual.nl/blueprints/precompiled.md): What precompiling does to execution speed and when to reach for it.
- [Remote access control](https://docs.rual.nl/blueprints/remote-access-control.md): Scopes, the scopes modal, rate limits and throttles on your own endpoints.
- [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.
- [Places and Geo Search](https://docs.rual.nl/blueprints/places.md): Search the built-in places dataset, filter by proximity and enrich your own documents with it.

## Interfaces
- [Interfaces overview](https://docs.rual.nl/interfaces.md): Building the front end: RUAL Studio, the component libraries, 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.
- [Components](https://docs.rual.nl/interfaces/components.md): How interface components are defined, configured and rendered.
- [RUAL Library](https://docs.rual.nl/interfaces/rual-library.md): The helper library available inside custom components.
- [RUAL Components](https://docs.rual.nl/interfaces/rual-components.md): The component set that ships with RUAL and the props each one takes.
- [RUAL Studio](https://docs.rual.nl/interfaces/rual-studio.md): The cluster management interface: where blueprints, storages and users are managed.
- [Handle Iterations](https://docs.rual.nl/interfaces/iterations.md): Render lists and repeat structures without fighting the renderer.
- [Overwrite Defaults](https://docs.rual.nl/interfaces/overwrite-default-pages.md): Replace the built-in login and system pages with your own.
- [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.

## 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.
- [Building User Authentication](https://docs.rual.nl/tutorials/user-authentication.md): Login, tokens, 2FA and the scope checks around them.
- [Creating a REST API](https://docs.rual.nl/tutorials/rest-api.md): A complete CRUD API with validation, paging and error replies.
- [Dashboard with Charts](https://docs.rual.nl/tutorials/dashboard-charts.md): Aggregate storage data and render it as a live dashboard.
- [File Upload & Processing](https://docs.rual.nl/tutorials/file-upload-processing.md): Accept an upload, store it as an asset and process it safely.
- [Email System Setup](https://docs.rual.nl/tutorials/email-system.md): Templates, sending and delivery handling for transactional email.
- [Third-Party Integrations](https://docs.rual.nl/tutorials/third-party-integrations.md): Call external APIs, keep credentials out of the canvas and handle failures.
- [Building AI Endpoints](https://docs.rual.nl/tutorials/ai-endpoints.md): Add Claude to a blueprint: messages, structured JSON replies, streaming, tools, cost control and batches.
- [Building a Login Page](https://docs.rual.nl/tutorials/login-page.md): Passwordless login: email a code, verify it into a session token, and the form page around it.
- [Building a Reporting API](https://docs.rual.nl/tutorials/reporting-api.md): Aggregations over storage, answered as a CSV or XLSX download or a scheduled email.
- [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.
- [Building an API with Locking](https://docs.rual.nl/tutorials/api-locking.md): Claim a lock around read-modify-write sections and always release it.
- [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, adoption and the blocks.

## Home Automation
- [Home Automation overview](https://docs.rual.nl/home-automation.md): Running the building the node sits in: Zigbee, Thread/Matter, Z-Wave, Philips Hue and Daikin devices, adopted into one vocabulary and automated by blueprints, with no vendor cloud in the loop.
- [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, and what survives a restart.
- [Trigger Reference](https://docs.rual.nl/home-automation/triggers.md): All 28 start-of-flow device blocks (20 released, 8 coming soon), 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.

## 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.
- [Simple Blog](https://docs.rual.nl/examples/simple-blog.md): Posts, slugs, tags and a published state.
- [E-Commerce Catalog](https://docs.rual.nl/examples/ecommerce-catalog.md): Products with variants, stock and category filtering.
- [User Management](https://docs.rual.nl/examples/user-management.md): Profiles alongside cluster users, teams and role changes.
- [Booking System](https://docs.rual.nl/examples/booking-system.md): Resources, time slots, conflict checks and reminders.
- [Inventory Tracker](https://docs.rual.nl/examples/inventory-tracker.md): Stock movements as an append-only log with derived levels.
- [Task Management](https://docs.rual.nl/examples/task-management.md): Boards, columns, assignees and due dates.

## Reference
- [Reference overview](https://docs.rual.nl/reference.md): Lookup material. Short pages you come back to rather than read once.
- [Block Quick Reference](https://docs.rual.nl/reference/block-quick-reference.md): The blocks you reach for daily, grouped by what they do.
- [API Endpoint Reference](https://docs.rual.nl/reference/api-endpoint-reference.md): Every cluster endpoint with its method, scope and reply shape.
- [System Settings Quick Ref](https://docs.rual.nl/reference/system-settings-quickref.md): System settings in one table, with defaults.
- [Component Props Reference](https://docs.rual.nl/reference/component-props-reference.md): Props, types and defaults for the built-in components.
- [Error Code Reference](https://docs.rual.nl/reference/error-code-reference.md): What each error code means and what usually causes it.
- [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.
- [DNS Zone Blocks](https://docs.rual.nl/reference/dns-blocks.md): Authoritative DNS from a storage: render a zone whole, check it everywhere, and push only what passed.

## Architecture
- [Architecture overview](https://docs.rual.nl/architecture.md): Decisions you make once per project, and the reasoning behind them.
- [Choosing Your Approach](https://docs.rual.nl/architecture/choosing-approaches.md): Blueprint, custom component or external service: which fits which problem.
- [Version Management](https://docs.rual.nl/architecture/version-guide.md): Release channels, safe upgrade routines and where breaking changes are documented.
- [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, 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 & Fixes](https://docs.rual.nl/troubleshooting/common-issues.md): Blueprints that do not respond, scope errors, stale caches and their fixes.
- [Debugging Blueprints](https://docs.rual.nl/troubleshooting/debugging.md): The console, the simulation popup, error pins and block revisions.

## 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