data-modeling

# Data modeling — entities, schema, and row-level security This app persists data with **Rayfin data**. You define entities as decorated TypeScript classes under `packages/data/src/`, register them in `packages/data/src/index.ts`, define their isomorphic contracts in `packages/shared/src/index.ts`, and read/write them with the typed client from `packages/frontend/src/lib/rayfin-client.ts` (`await getRayfinClient()`). ## Read the docs first — they ship in the packages **Rayfin's data rules are owned by the installed packages, not by this skill.** Decorators, field options, relationships, permissions, the query API and the platform's constraints all move between releases. Read them from disk: | You need… | Read | |---|---| | `@entity`, every field decorator, and their options | `node_modules/@microsoft/rayfin-core/assets/docs/decorators.md` | | Permissions end to end — `@role`, the policy DSL, claims, `include` / `exclude` | `node_modules/@microsoft/rayfin-guide/assets/docs/data/permissions.md` | | The `@anonymous` / `@authenticated` shorthands | `node_modules/@microsoft/rayfin-core/assets/docs/permissions.md` | | Entity authoring end to end, relationships, schema registration | `node_modules/@microsoft/rayfin-guide/assets/docs/data/overview.md` | | Reading and writing with the client | `node_modules/@microsoft/rayfin-guide/assets/docs/data/graphql.md` | | Paging, cursors, text-field nullability | `node_modules/@microsoft/rayfin-data/assets/docs/index.md` | | **Constraints that will bite you** — text length, FK naming, many-to-many, dialect | `node_modules/@microsoft/rayfin-guide/assets/docs/known-limitations.md` | Read `known-limitations.md` **before** you design entities. It is short, and it is where the platform tells you what it will not do. Everything below is about **this template** — what it turns on, where files go, and how its build is wired. For anything about Rayfin itself, use the table. ## Step 1 — turn the data service on The base template keeps the `data` service off, because a dashboard over a semantic model does not need a database. Turn it on for an app that needs persistence: ```sh npm run pack:add -- data-modeling ``` That flips `data.enabled` in `rayfin/rayfin.yml` and plants a starter entity in `packages/data/src/Item.ts`, registered in `packages/data/src/index.ts`, with its isomorphic contract in `packages/shared/src/index.ts`. Re-applying is safe: it keeps files you have edited, and `--force-seeds` is the explicit way back to the pack's version. The template authenticates before rendering app content through its dynamic auth provider and gate. Keep that boundary intact and follow the installed `rayfin-guide/assets/docs/auth/` pages for additional service-specific requirements. Preserve server-side entity permissions and row-level security. Do not replace an authentication failure with anonymous access or block the entire app because it is outside the Fabric portal. ## Step 2 — write entity files One file per entity under `packages/data/src/`, for example `packages/data/src/Note.ts`. Start from the seeded `Item.ts` — rename it and change the fields. Editing a working entity is more reliable than writing one from nothing. When the real model replaces the example, remove the unused starter `Item` runtime entity, its `packages/data/src/index.ts` registration, and its `packages/shared/src/index.ts` contract so it does not become user-visible. `@microsoft/rayfin-core`, `@microsoft/rayfin-data` and `@microsoft/rayfin-client` are already pinned in the base app — nothing to install. For the decorator set, field options, relationship syntax, FK naming and the many-to-many rule, read `rayfin-core/assets/docs/decorators.md` and `rayfin-guide/assets/docs/data/overview.md`, then `known-limitations.md`. ## Step 3 — register entities in this template's schema `packages/data/src/index.ts` starts with the seeded `Item` registration, while `packages/shared/src/index.ts` owns its isomorphic record contract and schema type map. Add every entity, including join entities, to both packages: ```ts // packages/shared/src/index.ts export interface NoteRecord { id: number; title: string; } export type UniversalAppSchema = { Note: NoteRecord; }; // packages/data/src/index.ts import { Note } from './Note.js'; export const schema = [Note]; ``` > The client's generic type comes from `UniversalAppSchema` (already referenced by > `packages/frontend/src/lib/rayfin-client.ts`), so add every entity to both the > `schema` array: one registered in the array but missing from the type is > reachable at runtime and invisible to the compiler. > > **Type-check with `tsc -b`, never `tsc --noEmit`.** The workspace packages are > referenced TypeScript projects, and the frontend client imports the shared > schema type, so > a bare `tsc --noEmit` fails with `TS6305` until the referenced project has been > built. Run `npm run typecheck` for the real referenced-project check. > `npm run build` uses `tsc -b --noCheck` for speed and does not prove the > entity types are correct. ## Step 4 — read and write The query chain, mutations, `findById`, filtering and paging are documented in `rayfin-guide/assets/docs/data/graphql.md` and `rayfin-data/assets/docs/index.md`. Use `await getRayfinClient()` from `packages/frontend/src/lib/rayfin-client.ts` inside an async query or mutation; that helper is this template's; the API it returns is the package's. For the interface over your entities — optimistic updates, forms, and the loading / empty / error states — read **`crud-ui`**, which ships the kit. ## Step 5 — per-user data "Each person sees only their own …" is a **server-side** `@role` policy, never a filter in the UI. A client-side filter still leaves the rows fetchable. Read `rayfin-guide/assets/docs/data/permissions.md` for the decorator, the typed policy DSL, the supported claims, logical composition, and field visibility — it is the fullest treatment. `rayfin-core/assets/docs/permissions.md` adds the `@anonymous` / `@authenticated` shorthands, owner-field typing, and owner stamping. Keep authentication and authorization on the data operations that require them. ## Notes - **Stable features only.** Use `@authenticated` / `@role('authenticated', …)`. Anonymous data access on Fabric requires a tenant admin switch — see `rayfin-guide/assets/docs/data/overview.md`. If asked for public data, say so and use authenticated access. - **Deploying ships the data model.** A schema change migrates on the next deploy. Read `app-deployment` and follow the installed, version-matched CLI guide. <!-- MAINTAINERS: this skill owns *this template* — the data service toggle, the workspace schema shape, the tsc -b build note, and the auth pairing. It does not own Rayfin. Rayfin's own rules are read at runtime from the installed packages' docs (`rayfinDocs.dir`, today `assets/docs`), so they cannot drift from the version a generated app actually has. That replaces the previous arrangement, where this file hand-mirrored rules from the CLI's bundled `skill:rayfin` and had to be diffed against it on every CLI bump. Drift under that arrangement had already shipped once: bare `@text()` appeared in every example here while the authoritative rule required an explicit `max` on MSSQL. -->