Choosing Your Approach
Blueprints or custom code? Storage or an external database? Real-time or polling? The honest trade-offs, decided per situation.
RUAL rarely forces a single way to build something. This guide lays out the recurring architecture choices and gives a default answer for each, so you decide once and move on.
Blueprints vs Custom React
| Situation | Choose | Why |
|---|---|---|
| CRUD apps, admin panels, forms, dashboards | Blueprints | State blocks render pages server-side; zero frontend code, instant auth and storage. |
| Highly custom interactions (drag & drop builders, rich editors, games) | Custom React component | The component system lets you mount your own React inside a RUAL page — see Components. |
| Data-heavy logic, integrations, scheduled work | Blueprints (functions) | Server-side, close to storage, queueable. |
| A pixel-perfect marketing site | Custom frontend on the APIs | Use RUAL as headless backend: cluster APIs + your own app. See API Guide. |
Rule of thumb: blueprint until a specific UI requirement forces you out, then drop to a React component inside the blueprint — not to a separate app.
RUAL Storage vs External Databases
| Situation | Choose |
|---|---|
| Application data, documents, orders, profiles, logs | RUAL storage — schema-less, searched by query blocks, zero ops. See Storages. |
| Legacy data that already lives elsewhere | External via API — wrap the system with http request blocks or custom APIs in front of it. |
| Heavy relational reporting across many entities | Hybrid — operational data in RUAL storage, periodic exports to your BI warehouse. |
| Millions of writes/hour, strict relational integrity | External database, with RUAL as the application layer on top. |
Storage is schema-less and denormalized by design — if you catch yourself wishing for joins, model for the read instead: embed what pages display (see Storage Examples).
Real-Time vs Polling
| Situation | Choose |
|---|---|
| Lists that should update as data changes (live dashboards, shared boards) | Real-time search — the page subscribes and re-renders on change. |
| External systems without webhooks | Polling — a repeating event that fetches on an interval and writes to storage. |
| Busy data with many concurrent readers | Cache + polling — real-time on hot data costs more than it saves; cache keys and short intervals usually win. See Common Pitfalls. |
One Big Blueprint vs Many Small Ones
- Default: one blueprint per component — a page, an API endpoint, or a named function set. It saves, deploys, and reviews as a unit.
- Share logic with functions, not more blocks — a public
trigger_custom_functionis the reuse boundary (see Best Practices). - Split when: a blueprint stops fitting on your mental screen, two people edit it at once, or a part needs its own deploy cadence.
- Keep together when: blocks only make sense as one transaction or one page — splitting adds indirection for nothing.
Decision Summary
- UI: blueprint pages first; React component inside the page when needed; external frontend last.
- Data: RUAL storage first; external only for legacy or extreme scale.
- Freshness: real-time for shared views, polling+cache for volume.
- Structure: many small blueprints joined by functions; split on people and deploy cadence, not on line count.