Table of contents
- 1. Overview & philosophy
- 2. Storage & sharding
- 3. Security & permissions
- 3.1 Easy
- 3.2 Aura (Advanced)
- 4. JSON parsing - the easiest place to break
- 5. Same method names - different behavior
- 5.1 Aura-only (list + auth)
- 5.2 Composite / index helpers lean Easy
- 6. FS, routes & backend functions
- 7. Typical development flows
- 8. Golden rules for codegen / asking AI
- 9. Method matrix (full)
- 10. Helpers - same on Easy and Aura?
- 11. Quick checklist (print and keep)
- 12. One-paragraph summary
Appifio Creator · Report BR02 · Technical comparison
Easy vs Aura Storage
a detailed comparison of the two backend models
a detailed comparison of the two backend models
Full side-by-side on philosophy, storage, security, JSON parsing, methods, FS/routes, helpers, codegen flow - and how to enable the right Prompt template so the AI generates for the Storage edition you actually run.
Critical - Prompt & skills
In Appifio Creator → Prompt & skills → Appifio prompt template → enable the document that matches your Backend edition. Then the AI Agent receives Prompt + skills automatically - you do not need to paste or attach Storage docs yourself.
| Backend edition | Enable this template (English title) |
|---|---|
| Easy (App Storage) | Appifio Easy Storage - Complete AI Guide |
| Advanced / Aura | Appifio Aura Storage (Advanced) - Complete AI Guide |
| Advanced + CMS | Aura Complete + Appifio Aura CMS + Storage - Complete AI Guide (AS19). CMS does not run on Easy. |
| (Optional) Shared frame | Appifio Storage - Shared Prompt Framework (Easy + Aura) - still pair with only one Easy or Aura guide |
Do not enable Easy + Aura Complete together. Stacking them mixes rules (JSON parse, appendData vs writeFile, auth…) → code for the wrong Storage edition vs your Backend tab.
Correct flow: (1) Backend tab → Easy or Advanced → Save → Save changes · (2) Prompt template: exactly one Easy or Aura guide (+ CMS guide if using CMS) · (3) Ask the AI to build.
Goals: Know when to pick Easy / Aura; never copy patterns across models; avoid parse / permission / list-wipe bugs; configure exactly one Prompt template.
Time: about 25-35 minutes
Audience: makers using Coder, AI codegen, people who already opened Backend (F01).
Read with: F01 · Easy API series EM01-EM09 · Aura series AM01-AM12 · BR01
Related: AM02 / AM03 (Aura list & flat) · EM02 / EM03 (Easy parse & one JSON ledger)
1. Overview & philosophy
| Easy (App Storage) | Aura / Advanced | |
|---|---|---|
| Goal | Small-medium apps, few records, light traffic (landing, biolink, form, small blog) | Larger apps, more data, more users, clear roles + CMS |
| Philosophy | One JSON ledger - each data type lives in one file; the browser loads all → edits → overwrites the whole file | Sharding - lists split into shards; client fetches only what it needs; less bandwidth / overwrite races |
| Who handles lists? | Mostly browser JS (find, paginate, add/remove on arrays) | Server helps via readList / appendData / updateData |
| CMS / MCP | Usually not a full CMS | Needs Advanced (+ matching account plan) |
One-liner: Easy = “load all, edit, write all back”. Aura = “shard, fetch the slice, patch the right place”. Same
appifio_client - two different API rulebooks.2. Storage & sharding
Shared: Same Appifio data store; same hostile filename filters, blocked executable extensions, dangerous-content scans.
| Point | Easy | Aura |
|---|---|---|
| How it stores | Each filename = one whole JSON blob | flat = whole blob (config sheets); indexed = master index + per-row shards |
| Internal shape | Server does not classify Object/Array - validate & store | Clear flat / indexed split |
| Long lists | Whole ledger in browser RAM | Fetch only needed fields via readList; each row is a hidden shard |
| Add / edit / delete one row | Edit object/array then writeFile the whole ledger | appendData (server assigns id) · updateData · delete = content null |
3. Security & permissions
3.1 Easy
- Primary protection: page session key (+ platform quota).
- No in-app admin accounts - do not build Aura-style login/admin.
- Anyone with the page session key has near-full mutation power: data store, page files, routes (via
appifio_client).
3.2 Aura (Advanced)
- Four levels: Guest → user → admin → superadmin (includes a
userrole, not only Guest/Admin). - Successful login → Aura client keeps the admin session and sends it on later requests.
- Auth is locked in
login.json- normalreadFile/writeFileto that file is blocked.
Aura rate limits (match product code - do not mix units):
- Failed logins: 5 / 10 minutes → IP block ~30 minutes
- Mutation spam: 60 / 1 minute / IP / link → block ~1 hour (not 60/hour)
- Backend function: 120 / 1 hour / IP / link
- Bad page-session-key attempts also have a separate block threshold
4. JSON parsing - the easiest place to break
| Method | Easy | Aura |
|---|---|---|
readFile | content = raw string → must JSON.parse (+ try/catch) | content is already object/array → do not parse again |
readList | N/A | Already parsed - use the array directly |
readFsFile (JSON) | Often still a string → parse if needed | e.g. routes.json may still be a string |
readField | value already decoded; missing file → success: false | Missing → success: true, value: null |
// Easy - correct
const r = await appifio_client.appifio_readFile('blog.json');
if (r.success && r.data.exists && r.data.content) {
const data = JSON.parse(r.data.content); // try/catch recommended
}
// Aura - correct (do NOT JSON.parse content)
const a = await appifio_client.appifio_readFile('blog.json', itemId);
const item = a.data.content; // already an object5. Same method names - different behavior
- Upload: Easy needs only the page session key. Aura
uploadImage/uploadFile→ admin login required. - findByName: Easy defaults to the data store with “contains” matching. Aura matches filenames on the data store.
- Route: Easy = client reads/writes
routes.json(composite JS). Aura = route API + admin required to write. - hardDelete: Aura usually needs superadmin.
- CMS / MCP: Easy usually lacks full CMS. Aura + matching plan → CMS panel (AS series).
5.1 Aura-only (list + auth)
appifio_readList- field-trimmed listappifio_appendData- append row (visitor/public for forms)appifio_updateData- update; delete item = contentnull(nodeleteData)- Auth:
login,logout,getSession,registerAdmin,changePassword,updateProfile, admin management… - Helpers:
validateAdminSession,isLoggedIn- do not replacegetSessionwhen entering admin pages
5.2 Composite / index helpers lean Easy
createContentWithRoute, ensureHandlerFile exist on both families. deleteContentWithRoute, updateContentIndex, removeFromContentIndex - Easy; Aura uses indexed/shards and composes updateData/removeRoute yourself.
6. FS, routes & backend functions
Both read/write the physical FS (HTML, assets) and use routes.json to map URL → file.
| Task | Easy | Aura |
|---|---|---|
| Read FS / list FS | Page session key | Guests can read |
| Write/delete FS, add/remove routes | Anyone with the key can usually do it | Admin required |
executeBackendFunction | Node sandbox | Same + tighter rate limits; Secrets separate from the client API (Panel config) |
Aura - guest pages: read only (
readFile/readList) + appendData for forms. Do not call writeFile / updateData / addRoute on the public frontend. Delete one list row = updateData(file, id, null) - there is no deleteData.7. Typical development flows
Easy
readFile('data.json')JSON.parse(...)- Edit in JS
writeFile(..., JSON.stringify(data))addRoute(slug, 'detail.html')
Aura
login→ token kept automatically- Guest form:
appendData - Admin list:
appendData/updateData - Pages:
writeFsFile+addRoute - List UI:
readList(..., fields) - Detail:
readFile(file, id)→ shard
8. Golden rules for codegen / asking AI
Easy - template: Appifio Easy Storage - Complete AI Guide
- Always parse after
readFile; do not invent Aura-style login/admin. - You still need the page session key - whoever has it ≈ full mutation.
readFieldmissing file →success: false.findByNameis data-store only.
Aura - template: Appifio Aura Storage (Advanced) - Complete AI Guide
- Do not hash admin passwords yourself; do not invent admin
users.json- use built-in Auth. - Lists: never
writeFilethe whole ledger → useappendData/readList/updateData. - Flat config/settings: still
readFile/writeFile. Wrap admin pages withgetSession().
9. Method matrix (full)
| Method | Easy | Aura |
|---|---|---|
createFile | Create (errors if exists) | With flat/indexed classification |
readFile | Returns string → need JSON.parse | Already parsed; optional id for one shard |
writeFile | Overwrite (page session key) | Overwrite (admin required) |
deleteFile / restoreFile | Soft delete / restore | Admin required |
hardDeleteFile | Permanent delete | Usually superadmin |
fileExists / getFileInfo / listFiles / searchFiles | Yes | Yes |
renameFile / copyFile | Yes | Admin required |
findByName | Data store only, “contains” | Exact name on data store |
readField | Missing → success: false | Missing → success: true, value: null |
writeField | Page session key | Admin required |
uploadImage / uploadFile | Page session key | Admin required |
readFsFile / listFsFiles / getFsFileInfo | Yes | Guests can read |
writeFsFile / deleteFsFile | Page session key | Admin required |
addRoute / removeRoute / getRoutes | Composite JS ↔ routes.json | API + admin to write |
executeBackendFunction | Node sandbox + Secrets (Backend tab) | Yes + tighter rate limits |
| Composite / index - Easy-leaning | ||
createContentWithRoute / ensureHandlerFile | ✅ | ✅ (similar family + auth/shards) |
deleteContentWithRoute / updateContentIndex / removeFromContentIndex | ✅ (EM04) | ❌ - use indexed + compose yourself |
| List / sharding - Aura only | ||
appendData / readList / updateData | ❌ | ✅ (delete row = updateData(..., null)) |
deleteData | ❌ | ❌ does not exist |
| Auth / CMS - Aura only | ||
login / logout / getSession / registerAdmin… | ❌ | ✅ (AM06) - wrap admin pages with getSession |
| CMS security / MCP / theme helpers | ❌ | ✅ CMS panel (AS series) |
Per-method detail + examples: Easy → EM01-EM09 · Aura → AM01-AM12. Do not mix the two series.
10. Helpers - same on Easy and Aura?
These JS helpers share the same logic family on Easy and Aura / Advanced appifio_client:
| Helper | Notes |
|---|---|
formatDateTime | UTC / …Z; presets date|time|datetime|full|iso|us|eu; respects window.__AURA_CMS_DISPLAY_FORMATS__ if present |
generateSlug | Same Vietnamese-friendly slug style |
formatFileSize, sanitize / extension / isImage / unique name | Aligned |
deepClone, debounce, getRouteSlug, getQueryParams | Aligned |
showError / showSuccess | Hooks window.showError / showSuccess if the page defines them |
Do not confuse: Shared helpers do not mean DB/FS APIs are shared (parse
readFile, missing-file readField, upload auth, route PHP vs composite…).11. Quick checklist (print and keep)
- Backend tab: Easy or Advanced → Save → Save changes.
- Prompt & skills → Appifio prompt template: enable one matching guide (English titles at the top).
- Do not enable Easy + Aura together; do not attach both doc sets into one chat.
- Easy
readFile/readFsFileJSON → mustJSON.parse(try/catch). - Aura
readFile/readList→ do not re-parsecontent. - Easy
readFieldmissing file →success: false; Aura →value: null. - Easy
findByName= data store only. - Aura delete list item =
updateData(..., null)- never calldeleteData. - Aura mutation rate = 60/minute (not /hour).
- Aura upload = admin; Easy = page session key only.
- Aura roles include user.
- Go deeper: Easy → EM01-EM09 · Aura → AM01-AM12 · CMS UI → AS · before client handoff: EM09 or AS17.
12. One-paragraph summary
Easy keeps a whole “ledger” in one JSON file that the browser loads, edits, and overwrites; protection is the page session key with no in-app admin. Aura shards lists, has Guest/user/admin/superadmin, rate limits, and dedicated list/auth methods. Date/slug helpers are nearly the same; differences live in JSON parsing,
readField, upload, routes, and how you mutate lists. For correct AI output: Backend and one Prompt template must both be Easy or both Aura - never both guides at once.Suggested next step
F01 → pick Backend → enable matching Prompt template → EM01 (Easy) or AM01 (Aura)
Easy: Appifio Easy Storage - Complete AI Guide · Aura: Appifio Aura Storage (Advanced) - Complete AI Guide
What the AI Agent can do: BR03
Internal navigation (same language)
Appifio Creator · Full comparison report · BR02
