Programming model overview

Rayfin SDK uses a decorator-driven programming model where you define your data schema once in TypeScript and automatically receive production-ready APIs, type-safe clients, and infrastructure.

Key concepts

Rayfin SDK combines three core elements:

• Decorator-driven schema: Use TypeScript decorators to define data models, permissions, and relationships.
• Automatic API generation: Your decorated classes become GraphQL endpoints without writing controller code.
• Type-safe clients: Generated TypeScript clients provide compile-time validation for queries and mutations.

How it works

When you create a Fabric app, your code flows through these stages:

1. Define data models with decorators

You define your data structure using TypeScript classes and decorators from @microsoft/rayfin-core:

import { entity, uuid, text, int } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @text({ optional: true }) description?: string;
  @int() price!: number;
}

2. Schema generation

The Rayfin CLI (npx rayfin) analyzes your decorated classes and generates:

• Database schema - Tables, columns, constraints, and indexes
• API configuration - GraphQL endpoint definitions
• Permission policies - Row-level security and field-level access control

4. Type-safe client usage

GraphQL APIs are available to perform CRUD operations on your database. Rayfin SDK provides a data client operation out of the box to read or write or delete data.

import { RayfinClient } from '@microsoft/rayfin-client';

const client = new RayfinClient();

// TypeScript knows about Product fields
const products = await client.data.products.query()
  .select(['id', 'name', 'price'])
  .execute();

// Compile-time error if field doesn't exist
const invalid = await client.data.products.query()
  .select(['nonexistentField'])  // ❌ TypeScript error
  .execute();

Decorator reference

Rayfin SDK provides decorators for common data modeling patterns:

Entity decorators

Property decorators

Permission decorators

See Define data permissions for authorization details.

Development workflow

A typical development cycle follows this pattern:

1. Define or modify data models - Add or update TypeScript classes with decorators
2. Test locally with remote backend - Run npm run dev to test your frontend code changes against your App backend in Fabric.
3. Deploy to Fabric - Run npx rayfin up to deploy to the managed Fabric service and applies your schema changes.

Changes to your TypeScript models automatically propagate through the entire stack — from database schema to API endpoints to client types.

Authorization

Permissions are defined alongside your data models using the @role decorator:

@entity()
@role('authenticated', ['create', 'read', 'update', 'delete'], {
  policy: (claims, item) => claims.sub.eq(item.userId)
})
export class UserDocument {
  @uuid() id!: string;
  @text() userId!: string;
  @text() content!: string;
}

This approach ensures:

• Security rules live next to the data they protect
• Type-safe policy expressions catch errors at compile time
• Refactoring entity fields automatically updates permission checks

Related content

• Data models overview
• Define data permissions
• Query data with GraphQL