taruvi-refine-providers

Taruvi Refine providers (frontend)

Single frontend skill for Taruvi. Covers everything that runs in the browser: wiring @taruvi/refine-providers, all Refine hook usage against Taruvi, production-ready list/dashboard/dropdown/upload UX, auth flow, and access control.

If the task is provisioning resources or authoring Python function bodies, switch to taruvi-app-developer.

Provider map

Provider	Refine key	Purpose
dataProvider(client)	default	Datatable CRUD, filters, pagination, aggregation, graph
storageDataProvider(client)	storage	File/object upload, list, download, delete
appDataProvider(client)	app	Function/analytics execution, roles, settings, secrets (via useCustom / useList / useOne)
userDataProvider(client)	user	User CRUD
authProvider(client)	authProvider prop	Login, logout, token refresh, identity, permissions
accessControlProvider(client)	accessControlProvider prop	Batched Cerbos checks for useCan / CanAccess

Hook support matrix and meta options live in overview.md.

Deprecated — do not use: functionsDataProvider, analyticsDataProvider. Use appDataProvider + useCustom with meta.kind: "function" or meta.kind: "analytics" instead.

Workflow

1. Read overview.md once — install, client setup, full provider/hook map.
2. Open the task-specific reference (table below).
3. Identify the installed package's current non-deprecated API. Don't ship new code on a deprecated surface just because old examples exist.
4. Apply the production-ready defaults (next section).
5. Walk the UI for each role before reporting done — confirm list actions, create buttons, and menu items show/hide correctly.

Reference index

Task	Read
Database CRUD, filters, aggregation, graph	database-provider.md
File upload, batch delete, metadata, filters	storage-provider.md
Function execution, analytics, roles, settings, secrets	app-provider.md
User CRUD	user-provider.md
Login, logout, token flow, identity	auth-provider.md
useCan, CanAccess, prefixed ACL resources	access-control-provider.md
TypeScript types, deprecated migration	types-and-utilities.md

Production-ready defaults

Unless the user explicitly scopes down, every frontend deliverable must meet these. They are non-suggestion.

Lists / tables

• Backend pagination by default. Default pageSize 10; expose 10 / 20 / 50 / 100.
• Server-side search, filter, sort — pushed into provider filters / sorters, never re-applied to fetched rows in React.
• Visible search input + relevant filter controls (status, department, date range) — debounce search 300–500ms.
• One primary search control per page (don't duplicate DataGrid quick filter with a separate page search on the same fields).
• MUI DataGrid → use useDataGrid. Hand-wiring useList + component state is a documented exception, not a default.

Dashboards / KPIs / charts

• Default: datatable aggregate + groupBy via useList with meta.aggregate: ["count"] (note the array — aggregate: "count" fails silently). For cross-table needs, the data provider supports populate and aggregation together — try that first; aggregating over populated FK fields usually does the job.
• Analytics queries are the exception, not the default. Reach for appDataProvider + useCustom({ meta: { kind: "analytics" } }) only when (a) the source is an external database or (b) the SQL genuinely cannot be expressed via the data provider — multi-table joins with grouped aggregation, window functions, recursive CTEs, etc. Registering a query is a separate backend round-trip (taruvi-app-developer); avoid it for anything a single useList with meta.aggregate + meta.populate can do.
• Never fetch full row sets into React to derive summary metrics.
• Graph queries must set an explicit depth.
• having only works after groupBy. Use filters for pre-aggregation filtering.

Network-backed dropdowns

• Autocomplete (or equivalent typeahead), not static Select.
• Paginated backend queries (default option pageSize 10), debounced search pushed into provider filters. No client-side filtering over a one-shot load.

File uploads / attachments

• Multi-file UX by default. Report per-file success/failure — never an all-or-nothing aggregate.
• Chunk batch uploads to ≤10 files / ≤100MB; chunk batch deletes to ≤100 paths.
• Quota is advisory — surface as a warning, not an upload blocker.
• Warn on overwrite — upload silently replaces existing paths.
• Set visibility at bucket level; per-object override wins over bucket default.

Bulk actions

• Backend bulk ops (updateMany, deleteMany) for single-resource; serverless function for multi-resource cascades.
• Show selection scope clearly (selected rows vs filtered set), surface partial-failure details, invalidate affected queries.

Notifications

Use the wired Refine notificationProvider (useNotification). Don't add a parallel toast/snackbar system.

Contract rules (mandatory)

Function execution

useCustom({
  url: "<function-slug>",
  method: "post",
  dataProviderName: "app",
  payload: { /* inputs */ },
  meta: { kind: "function" },
});

payload carries inputs — not values, not config.payload.

Analytics execution

Same shape with meta: { kind: "analytics" }.

Access control

• useCan / CanAccess resources use prefixed ACL strings — datatable:employees, function:employee-terminate, query:hrms-dashboard-summary. Never params.entityType, never a bare resource name.
• Map UI actions to canonical Cerbos actions before checking: list / show → read, edit → update, create → create, delete → delete, execute for functions/queries.
• Verify the runtime payload — /check/resources's resource.kind must exactly match the requested resource string.
• Don't debounce or throttle useCan manually — accessControlProvider already batches via DataLoader.

Client setup

const client = new Client({
  apiKey: import.meta.env.VITE_TARUVI_API_KEY,
  appSlug: import.meta.env.VITE_TARUVI_APP_SLUG,
  apiUrl: import.meta.env.VITE_TARUVI_API_URL,
});

<Refine
  dataProvider={{
    default: dataProvider(client),
    storage: storageDataProvider(client),
    app: appDataProvider(client),
    user: userDataProvider(client),
  }}
  notificationProvider={useNotificationProvider}
  authProvider={authProvider(client)}
  accessControlProvider={accessControlProvider(client)}
/>

Env vars use the framework's browser-exposing prefix (VITE_*, REACT_APP_*, NEXT_PUBLIC_*). Never hardcoded.

Gotchas worth surfacing here

The non-obvious ones. Per-domain pitfalls live in the references.

• 401 vs 403 — 401 = expired session (re-login). 403 = forbidden (show denied). Treating 403 as 401 causes infinite re-login loops.
• _cachedUser after role change — identity is cached module-locally and only clears on logout(). After admin role changes, force re-login or invalidate ["identity"] and ["access-control"] query keys.
• useCustom for async functions — async returns a task_id, not a result. Either keep the function sync (<30s) or wire a polling pattern with a separate status-check function.
• dataProviderName missing — useCustom / useCreate without the right dataProviderName routes to default, returning confusing "resource not found" errors. Always set "app" for functions/analytics and "storage" for buckets.
• Prefilled form fields — set InputLabelProps: { shrink: true } on TextFields with default values so the label doesn't overlap.
• aggregate must be an array — aggregate: "count" silently fails. Use aggregate: ["count"].
• Client-side filtering on backend data — fetching a page of rows and filtering in React is a correctness and scalability bug. Always push state into provider queries.