# Rayfin

> Define your backend in TypeScript: database, type-safe APIs, Entra ID auth, functions, storage, and hosting. Rayfin deploys it to Microsoft Fabric — inside your organization's boundary.

Rayfin is a backend platform for TypeScript developers. You define entities as decorated
TypeScript classes; Rayfin generates the database schema, REST and GraphQL APIs, and
type-safe clients, then runs them on Microsoft Fabric with auth, functions, blob storage,
and static hosting built in.

## How to use these docs as an agent

- Append `.md` to **any** documentation route to get that page as clean Markdown.
  Example: https://rayfin.ai/docs/data/querying -> https://rayfin.ai/docs/data/querying.md
- [AGENTS.md](https://rayfin.ai/AGENTS.md) contains the short operating rules for writing Rayfin code.
- Start with [Rules for coding agents](https://rayfin.ai/docs/reference/agent-rules) before generating any Rayfin code.
- Every page carries `sdk_version`, `cli_version` and `last_updated` in its frontmatter.
  Do not mix API shapes across SDK versions.

Documented against `@microsoft/rayfin-*` v1.34.0 and `@microsoft/rayfin-cli` v1.33.2.

## Bulk downloads

Prefer a section bundle over the full corpus unless you genuinely need everything.

- [llms-full.txt](https://rayfin.ai/llms-full.txt): every page in one file, 689.6 KB (~176k tokens)

- [Overview](https://rayfin.ai/llms-full/docs.txt): 1 page, 7.3 KB (~2k tokens)
- [Get started](https://rayfin.ai/llms-full/start.txt): 4 pages, 24.5 KB (~6k tokens)
- [Data](https://rayfin.ai/llms-full/data.txt): 11 pages, 86.9 KB (~22k tokens)
- [Auth](https://rayfin.ai/llms-full/auth.txt): 5 pages, 42.6 KB (~11k tokens)
- [Functions](https://rayfin.ai/llms-full/functions.txt): 5 pages, 31.2 KB (~8k tokens)
- [Connectors](https://rayfin.ai/llms-full/connectors.txt): 8 pages, 101.2 KB (~26k tokens)
- [Storage](https://rayfin.ai/llms-full/storage.txt): 1 page, 4.7 KB (~1k tokens)
- [Hosting](https://rayfin.ai/llms-full/hosting.txt): 2 pages, 12.0 KB (~3k tokens)
- [Deploy](https://rayfin.ai/llms-full/deploy.txt): 7 pages, 49.8 KB (~13k tokens)
- [Recipes](https://rayfin.ai/llms-full/recipes.txt): 3 pages, 44.6 KB (~11k tokens)
- [Reference](https://rayfin.ai/llms-full/reference.txt): 35 pages, 287.7 KB (~73k tokens)

# Docs

- [Rayfin](/docs): Define your data model in TypeScript. Rayfin generates the database and type-safe APIs, then runs them on Microsoft Fabric — with auth, functions, storage, and hosting built in.

- **Get started**
- [Installation](/docs/start/installation): Install Node.js 20+ and the GitHub CLI on Windows, macOS, or Linux, then verify and update the Rayfin CLI.
- [Quickstart](/docs/start/quickstart): Scaffold a Rayfin project, deploy it to Microsoft Fabric, and run the frontend locally — from nothing to a running app in four commands.
- [Project structure](/docs/start/project-structure): The rayfin/ folder layout — rayfin.yml, entities under rayfin/data/, schema.ts, generated files, and how the frontend picks up backend config.
- [Deploy to Fabric](/docs/start/deploy-to-fabric): Enable Fabric apps in your tenant, create one in the Fabric portal, and deploy your project with rayfin login and rayfin up.

- **Build**
- Data: Model entities in TypeScript and query them with a type-safe client.
  - [Data](/docs/data): Model entities once as decorated TypeScript classes and get a database schema, GraphQL API, type-safe client, permissions, and validation from the same source.

  - **Model**
  - [Modeling entities](/docs/data/modeling): Define Rayfin entities as decorated TypeScript classes in rayfin/data/ and register them in schema.ts to get a database table and a typed API.
  - [Field types](/docs/data/field-types): Complete reference for Rayfin's field decorators — @uuid, @text, @int, @decimal, @boolean, @date, @email, @set, and @blob — and the options each accepts.
  - [Relationships](/docs/data/relationships): Model one-to-many associations between Rayfin entities with @one and @many, and work around the lack of native many-to-many support.
  - [Permissions and row-level security](/docs/data/permissions): Secure Rayfin entities with @role, @anonymous, and @authenticated, including row-level policies, field visibility, action-specific rules, and multi-tenant scoping.

  - **Read and write**
  - [Querying](/docs/data/querying): Read Rayfin entities with the type-safe select/where/orderBy/execute chain, including filtering, sorting, and cursor pagination.
  - [Aggregations](/docs/data/aggregations): Compute sums, averages, minimums, maximums, and counts over your entities with groupBy() and aggregate(), including grand totals and having filters.
  - [Creating, updating, deleting](/docs/data/mutations): Create, update, and delete Rayfin records through the type-safe client, and set relationship fields correctly in mutations.
  - [Validation](/docs/data/validation): Generate a Standard Schema validator directly from a Rayfin entity to validate form input without a separate validation library.

  - **Operate**
  - [Schema changes](/docs/data/migrations): Apply Rayfin entity changes to the database with rayfin up and rayfin up db apply, and verify the schema actually reached the server.
  - [Seeding data](/docs/data/seeding): Populate @anonymous() Rayfin entities with RayfinServerClient in a Node.js script — @authenticated() entities have no scripted seeding path today.
- Auth: Sign users in with Fabric SSO (Entra ID).
  - [Auth](/docs/auth): Sign users in with Fabric SSO — Rayfin's managed sessions, per-user data isolation, and one client API for every deployed app.
  - [Fabric SSO](/docs/auth/fabric-sso): Sign users in with their Microsoft Entra identity through the Fabric portal — enable it in rayfin.yml, install the provider package, and call ensureSignedInWithFabric.
  - [Sessions](/docs/auth/sessions): How Rayfin's opaque session object works — subscribe with onSessionChange, gate UI on isAuthenticated, and let Rayfin manage tokens for you.
  - [Delegated access](/docs/auth/delegated-access): Understand how Fabric SSO, function connections, connectors, and entity permissions use the signed-in user's identity.
  - [React integration](/docs/auth/react): An auth context, a useAuth hook, and route guarding for React apps built on the Rayfin auth client with Fabric SSO.
- Functions: Run server-side TypeScript alongside your data.
  - [Functions](/docs/functions): Run server-side TypeScript in Rayfin — when to use functions instead of client-side data access, and how to enable and scaffold them.
  - [Writing a function](/docs/functions/writing-functions): The rayfin/functions project layout, registering functions with udf.func in function_app.ts, typed data access, and the auto-generated types.ts schema.
  - [Connections](/docs/functions/connections): Connect a Rayfin function to external services with delegated auth — AudienceType values, the ctx.getToken() pattern, and SQL/Key Vault/OneLake examples.
  - [Calling functions from your app](/docs/functions/calling-functions): Invoke Rayfin functions from the frontend with a type-safe FunctionClient — client.functions.<name>.invoke() and error handling.
  - [Deploying functions](/docs/functions/deploying): How Rayfin functions ship to Fabric with rayfin up, and how to deploy just the functions project with rayfin up functions deploy.
- Connectors: Query Fabric warehouses, SQL databases, semantic models, and KQL databases from your app.
  - [Connectors](/docs/connectors): Read and write existing Microsoft Fabric data — warehouses, SQL databases, Lakehouse SQL endpoints, semantic models, and KQL databases — from a Rayfin app.
  - [Adding a connector](/docs/connectors/adding): Discover Fabric sources, add a connector to rayfin.yml, install its pinned packages, and manage connector entries safely.
  - [Wiring connectors into your app](/docs/connectors/client-setup): Configure ConnectorsRayfinClient with connector schemas, runtime hooks, and browser-safe schema imports.
  - [Fabric SQL sources](/docs/connectors/sql-sources): Read and write Fabric SQL connector entities from Rayfin apps, including query chains, by-key reads, mutations, defaults, and troubleshooting.
  - [Generating entity files](/docs/connectors/entity-generation): Generate Category A connector entity files from metadata.json, including keys, relationships, permissions, aggregate schema, and apply steps.
  - [Semantic models](/docs/connectors/semantic-models): Run DAX against a Fabric semantic model from a Rayfin app and handle typed table results, row limits, and connector diagnostics.
  - [KQL databases](/docs/connectors/kusto): Run KQL queries and Kusto management commands against a Fabric KQL Database from a Rayfin app.
  - [Connector authentication](/docs/connectors/auth): Configure connector auth.type values, validation rules, and caller identity for delegated and application connector access.
- Storage: Store and serve files with the blob storage client.
  - [Storage](/docs/storage): What's documented so far about Rayfin's blob storage — the @blob() decorator, storage permissions, and the storage service flag in rayfin.yml.
- Hosting: Serve your frontend from the same app as your backend.
  - [Static content hosting](/docs/hosting): Deploy your built frontend alongside your Rayfin backend with staticHosting in rayfin.yml — configuration, deployment, limits, and troubleshooting.
  - [Redirect URIs](/docs/hosting/redirect-uris): Configure allowedRedirectUris in rayfin.yml for auth callbacks and the Fabric SSO handoff, and understand what rayfin up appends automatically.

- **Ship**
- Deploy: Ship your app to Microsoft Fabric.
  - [Deploy](/docs/deploy): Deploy a Rayfin project to a managed Fabric app with the rayfin up CLI workflow, then manage secrets, environments, and billing.
  - [Fabric apps](/docs/deploy/fabric-apps): What a managed Fabric app is, its prerequisites and child services, and how to create and manage one from the Microsoft Fabric portal.
  - [Deploying with rayfin up](/docs/deploy/rayfin-up): Deploy a Rayfin project to Microsoft Fabric with rayfin up, covering login, useful flags, deployment metadata, and redeploys.
  - [Secrets](/docs/deploy/secrets): Set API keys and tokens on a deployed Fabric app with rayfin secret set, so they stay server-side and never reach client code.
  - [Environments and configuration](/docs/deploy/environments): Every environment variable file, prefix, and resolution rule Rayfin tooling reads, from frontend-visible variables to interpolation in rayfin.yml.
  - [Capacity and billing](/docs/deploy/pricing): How Fabric capacity billing works for a deployed Rayfin app, and which operations consume Capacity Units and which do not.
  - [Deployment troubleshooting](/docs/deploy/troubleshooting): Symptom-to-fix reference for the most common failures when deploying a Rayfin project to Microsoft Fabric.
- Recipes: End-to-end walkthroughs for common application patterns.
  - [Recipes](/docs/recipes): End-to-end walkthroughs that combine Rayfin's data, auth, and deployment features into complete application patterns.
  - [Build a todo app](/docs/recipes/todo-app): Build a Fabric-authenticated todo app end to end, from a per-user data model through a React UI to a deploy on Microsoft Fabric.
  - [Testing a Rayfin app](/docs/recipes/testing): Test a Rayfin app's data and auth logic in Vitest without a live backend, using a swappable auth service and an in-memory fallback.

- **Reference**
- [Reference overview](/docs/reference): Landing page for the complete Rayfin reference — CLI commands, configuration schema, SDK packages, rules for coding agents, known limitations, deprecations, and troubleshooting.
- CLI: Every rayfin command, flag, and subcommand.
  - [CLI](/docs/reference/cli): Overview of the rayfin CLI — installation, the typical scaffold-to-deploy workflow, and an index of every command page in this reference.
  - [CLI installation](/docs/reference/cli/installation): Install the Rayfin CLI as a project dev dependency, globally, or run it ad hoc with npx — plus how to verify the install and update it.
  - [Init](/docs/reference/cli/init): Scaffold a new Rayfin project with npm create, add Rayfin to an existing one with rayfin init, or reconfigure an existing project's services.
  - [Login](/docs/reference/cli/login): Authenticate the CLI with Entra ID for Fabric operations — rayfin login, login status, logout, service principal auth, and where tokens are stored.
  - [Up](/docs/reference/cli/up): rayfin up deploys to Microsoft Fabric and applies pending schema migrations in one step — plus every up subcommand for status, schema, and static hosting.
  - [Secret](/docs/reference/cli/secret): rayfin secret set and secret list manage secrets on a deployed Rayfin item — masked interactive input, names/timestamps only, no bulk .env import.
  - [Env](/docs/reference/cli/env): rayfin env emits a framework-specific .env.local from rayfin/.env — flags, auto-detection, and why scaffolded projects run it in predev and prebuild.
  - [rayfin functions](/docs/reference/cli/functions): rayfin functions init scaffolds a serverless TypeScript Functions project under rayfin/functions/ that shares entity types with your Rayfin data model.
  - [Connector](/docs/reference/cli/connector): rayfin connector manages external Fabric sources, from discovery and registration through inspection and invocation.
  - [Docs](/docs/reference/cli/docs): rayfin docs search, get, list, discover, and catalog show — query version-locked Rayfin documentation from the terminal when the MCP server isn't available.
  - [Ai-files](/docs/reference/cli/ai-files): rayfin init ai-files install and status manage AGENTS.md, .mcp.json, and the Rayfin skill — flags, conflict resolution, exit codes, and the drift nudge in rayfin up.
  - [Templates](/docs/reference/cli/templates): Where Rayfin project templates come from — built-in, git, and local sources, registering your own template sources, and authoring a template.
  - [Telemetry](/docs/reference/cli/telemetry): What the Rayfin CLI collects, what it explicitly does not, and how to opt out with RAYFIN_TELEMETRY_OPTOUT.
- Configuration: rayfin.yml and environment variable reference.
  - [Configuration](/docs/reference/config): Landing page for Rayfin configuration reference — rayfin.yml schema, the exhaustive environment variable table, and ${VAR} interpolation syntax.
  - [rayfin.yml reference](/docs/reference/config/rayfin-yml): The complete rayfin.yml schema, key by key — id, services.auth, services.data, services.storage, services.staticHosting, services.functions, and connectors.
  - [Environment variables](/docs/reference/config/environment-variables): The canonical, exhaustive reference for every environment variable the Rayfin CLI and runtime read or write — frontend, tooling, feature flags, and file locations.
  - [Environment variable interpolation](/docs/reference/config/env-interpolation): The ${VAR} and ${VAR:-default} syntax Rayfin supports inside rayfin.yml — usage, .env file location, resolution priority, type coercion, and error handling.
- SDK: API reference for every @microsoft/rayfin-* package.
  - [SDK](/docs/reference/sdk): Which @microsoft/rayfin-* package to install for each capability, how they depend on each other, and version notes for the whole family.
  - [@microsoft/rayfin-core](/docs/reference/sdk/rayfin-core): Complete decorator reference for @microsoft/rayfin-core — entities, field types, relationships, and permissions that generate Data API Builder configuration.
  - [@microsoft/rayfin-client](/docs/reference/sdk/rayfin-client): RayfinClient construction, configuration options, and the client.data, client.auth, and client.functions facades, with exact signatures from the SDK.
  - [@microsoft/rayfin-data](/docs/reference/sdk/rayfin-data): The fluent GraphQL query and mutation API behind client.data — select, where, orderBy, pagination, and CRUD methods with exact signatures.
  - [@microsoft/rayfin-auth](/docs/reference/sdk/rayfin-auth): The Auth client surface — signOut, session management, and the OpaqueSession shape — with exact signatures from the SDK.
  - [@microsoft/rayfin-auth-provider-fabric](/docs/reference/sdk/rayfin-auth-provider-fabric): Fabric brokered authentication for Rayfin apps — ensureSignedInWithFabric, the embedded and popup flows, and the origins each one works from.
  - [@microsoft/rayfin-functions](/docs/reference/sdk/rayfin-functions): FunctionClient, the FunctionsSchema type, and client.functions.<name>.invoke() for calling serverless functions from the Rayfin SDK.
  - [@microsoft/rayfin-storage](/docs/reference/sdk/rayfin-storage): Type-safe blob storage client for Rayfin — what it's for and how to model storage folders today, pending a version-locked API reference.
  - [@microsoft/rayfin-connectors](/docs/reference/sdk/rayfin-connectors): Connector runtime APIs for mounting typed Fabric SQL, semantic model, and KQL Database connectors on the Rayfin client.
  - [@microsoft/rayfin-connector-fabric-graphql](/docs/reference/sdk/rayfin-connector-fabric-graphql): Type-only marker APIs for Category A Fabric SQL connectors that expose typed entity CRUD through client.connectors.
  - [@microsoft/rayfin-connector-fabric-semanticmodel](/docs/reference/sdk/rayfin-connector-fabric-semanticmodel): Marker, runtime, direct execution, URL parsing, Arrow decoding, and normalized result APIs for Fabric semantic model connectors.
  - [@microsoft/rayfin-connector-kusto](/docs/reference/sdk/rayfin-connector-kusto): Marker, runtime, config, raw response, and normalization APIs for Fabric KQL Database connectors.
  - [@microsoft/rayfin-lib](/docs/reference/sdk/rayfin-lib): The shared ApiClient, error classes, and small utilities every other Rayfin SDK package builds on — an internal dependency most builders never import directly.
- [Rules for coding agents](/docs/reference/agent-rules): The condensed set of rules and anti-patterns for writing Rayfin code — read this before generating entities, queries, permissions, or deployment commands.
- [Known limitations](/docs/reference/known-limitations): Current constraints in the Rayfin data client, Data API Builder, relationships, auth, and schema apply — organized by area, each with a workaround.
- [Deprecation warnings](/docs/reference/deprecations): How to silence Rayfin's deprecation warnings in application code, in Node.js scripts, and in browser apps.
- [Errors and troubleshooting](/docs/reference/errors): A symptom-to-fix index of the errors Rayfin builders hit most — deployment, schema apply, secrets, static hosting, and Fabric auth.