@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.1

package/assets/docs/index.md

@@ -1,52 +1,99 @@
 ---
-symbols: []
+sidebar_position: 1
 ---
 
-# Rayfin platform overview
-
-Rayfin is Microsoft's platform for building data-driven applications
-on Microsoft Fabric. It combines:
-
-- **Code-first data modeling** via TypeScript decorators (the
-  `@microsoft/rayfin-core` package's `@entity()`, `@text()`, `@uuid()`,
-  `@one()`, `@many()`, `@anonymous()`, `@authenticated()`).
-- **DAB-compliant data access** via `@microsoft/rayfin-data` exposing
-  GraphQL clients generated from your decorated entity classes.
-- **Authentication** via `@microsoft/rayfin-auth` with magic-link and
-  Fabric-token flows.
-- **A high-level client entrypoint** (`@microsoft/rayfin-client`) that
-  composes auth + data behind a single configured client.
-- **A scaffolding CLI** (`@microsoft/rayfin-cli`) that generates DAB
-  configuration from your entity classes and bootstraps new projects.
-- **An MCP server** (`@microsoft/rayfin-mcp`) that exposes the docs
-  corpus as `list_docs`, `search_docs`, and `get_doc` tools for AI
-  agents working in Builder projects.
-
-## Where to start
-
-For Builders new to Rayfin, follow the [quickstart](./quickstart.md).
-The quickstart walks through:
-
-1. Scaffolding a new Rayfin project with `npm create rayfin@latest`.
-2. Defining your first entity with the core decorators.
-3. Running the project locally with `rayfin up`.
-4. Querying via the generated GraphQL endpoint.
-
-## Per-package reference
-
-Each Rayfin SDK package ships its own docs at
-`<package>/assets/docs/`. Discoverable via:
-
-```bash
-rayfin docs list --module ts-sdk
-rayfin docs search 'magic link'
-rayfin docs get --id rayfin-auth:index.md
+# Overview
+
+Rayfin is a backend platform for TypeScript developers who want to model data once and receive production ready APIs, clients, and infrastructure.
+It combines decorator driven schema generation, a batteries included CLI, and backend services you can run locally or in production.
+
+> **TypeScript only** — Rayfin currently supports TypeScript as the only language for data models, client code, and application logic.
+
+## Who is a Rayfin Builder?
+
+A **Rayfin Builder** is an application developer who uses the Rayfin SDK to build modern TypeScript SaaS applications.
+As a builder, you focus on creating great user experiences while Rayfin handles the backend infrastructure.
+
+### Rayfin Platform vs Rayfin Applications
+
+- **Rayfin Platform**: A modern Backend-as-a-Service (BaaS) platform built for the agentic era that provides ready-to-use backend infrastructure
+- **Rayfin App/Project**: Applications built using the Rayfin SDK, leveraging the platform's capabilities
+- **Rayfin Builder**: App developers (you!) who build applications using Rayfin
+- **Rayfin Contributor**: Platform developers who work on Rayfin itself (see [contributor docs](https://github.com/microsoft/project-rayfin?tab=contributing-ov-file))
+
+## How to run Rayfin
+
+Rayfin is available in two modes.
+Choose the one that fits your stage and requirements.
+
+| | **Rayfin Local** | **Fabric Data App in Fabric** |
+| --- | --- | --- |
+| **What it is** | Open-source, self-hostable backend stack | Managed service for Rayfin on Microsoft Fabric |
+| **Authentication** | Entra ID, Email password | Fabric SSO (Entra ID single sign-on only) |
+| **Database** | MSSQL, PostgreSQL | MSSQL only |
+| **Data models & APIs** | ✅ | ✅ |
+| **Type-safe clients** | ✅ | ✅ |
+| **Static hosting** | ✅ | ✅ |
+| **CLI tooling** | ✅ | ✅ |
+| **Infrastructure** | You host (Docker, VMs, or any cloud) | Fabric manages hosting, scaling, and networking |
+
+Both modes share the same SDK, CLI, and data-modeling workflow.
+Start locally, then deploy to Fabric when you need a managed service — or stay self-hosted.
+
+## What Rayfin Provides
+
+- **Data models to APIs**: Decorate TypeScript classes and Rayfin generates database schemas plus REST and GraphQL endpoints automatically.
+- **Type safe clients**: Type-safe clients provide validation of queries and mutations before they ever hit the backend.
+- **Infrastructure automation**: Use Rayfin CLI tooling to spin up Rayfin stack provisions Data API Builder, authentication, database, and more so you can focus on product code.
+- **Opinionated security**: Permissions, row level filters, and per entity auth rules are configured next to your models.
+
+## Fabric Data App (Managed Service) Architecture
+
+```mermaid
+flowchart TB
+  Dev[Developer] -->|rayfin up| CLI[Rayfin CLI]
+  CLI -->|deploy| Fabric
+
+  subgraph Fabric[Microsoft Fabric]
+    direction LR
+    StaticApp[Static Content]
+    WebService[WebService]
+    DataApi[Data API Builder]
+    MSSQL[(MSSQL)]
+  end
+
+  User[End User] --> StaticApp
+  StaticApp --> WebService
+  WebService --> DataApi
+  DataApi --> MSSQL
+  WebService -->|Fabric SSO| EntraID[Entra ID]
 ```
 
-Or, in MCP-host environments, via the `list_docs`, `search_docs`, and
-`get_doc` tools.
+When you deploy with `rayfin up`, the CLI packages your project and provisions it as a Fabric data app.
+Fabric manages hosting, networking, and scaling.
+Authentication uses Fabric SSO (Entra ID single sign-on) exclusively — no other auth providers are available after deployment.
+
+Learn more about [Fabric Data App in Fabric](./app-backend/index.md) including child services, deployment, and management.
+
+## Key Components
+
+### Rayfin CLI
+
+The CLI installs via `npm create @microsoft/rayfin@latest`.
+It can scaffold new projects, launch local infrastructure, sync schema changes, and bundle templates for distribution
+
+### TypeScript SDKs
+
+- `@microsoft/rayfin-core` hosts the decorator runtime and metadata analysis helpers.
+- `@microsoft/rayfin-client` wires auth, data into a single facade for apps.
+- `@microsoft/rayfin-data` exposes GraphQL fluent (`client.data.gql`) APIs.
 
-## Package discovery
+## Next Steps
 
-If a package is not installed yet, use `rayfin docs discover '<topic>'`
-to find matching Rayfin packages and install commands.
+- Follow the [Quick Start Guide](./getting-started/index.md) to spin up your first Rayfin project in minutes.
+- Dive into [Data Models & Decorators](./data/overview.md) to understand how entities map to DAB.
+- Learn how to connect frontends with the [GraphQL guide](./data/graphql.md).
+- Configure authentication with [Rayfin Auth](./auth/overview.md).
+- Deploy frontends with [Static Content Hosting](./hosting/index.md).
+- Explore CLI capabilities in [CLI Guide](./cli/index.md).
+- Review [Known Limitations](./known-limitations.md) for current behaviors and workarounds.

package/assets/docs/known-limitations.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 80
+---
+
+# Known Limitations
+
+Current limitations and recommended workarounds for Rayfin Builders.
+
+## Data Client
+
+- `count()` is not available on the fluent GraphQL client.
+Select minimal fields and compute `results.length` instead.
+- Many-to-many relationships are not supported.
+Use an explicit join entity with two `@one()` navigations instead.
+
+## Data API Builder (DAB)
+
+Some query limitations are imposed by Data API Builder.
+See [Data known limitations](./data/index.md#known-limitations).
+
+## Relationships
+
+- Rayfin auto-generates foreign key columns when you define `@one()` or `@many()` navigation decorators.
+Define foreign key fields only when you need them in application code.
+- When you do define a foreign key field, it must follow the `{property}_id` naming convention.
+Custom key names (`foreignKey`, `targetKey`) are not supported on relationship decorators.
+- `@one()` and `@many()` accept `{ optional?, unique? }` options only.
+
+## Auth
+
+- The session change callback is `onSessionChange`.
+`onAuthStateChange` does not exist on the Rayfin auth client.
+- Session objects are opaque.
+Gate UI logic on `isAuthenticated` or the presence of a `user` property.
+- After enabling or disabling auth in `rayfin.yml`, restart the backend to expose the updated endpoints.
+
+## Data
+
+- `@entity()` does not accept composite field constraints; define constraints on individual fields via field decortor options.
+- Prefer `@anonymous()` and `@authenticated()` shorthands over `@role('anonymous', ...)` and `@role('authenticated', ...)`.
+
+## Database and Schema Apply
+
+- Run `npx rayfin up` and wait for services to be created before running `npx rayfin up db apply`.
+- If you see `unsupported UUID` errors, another service may be running on the default port with a different database dialect.
+- Enabling `data: enabled: true` in `rayfin.yml` requires `dialect: mssql` (or `postgresql`).
+- Omitting `dialect` causes a 400 error at deploy time: "Dialect is required when Data module is enabled."
+- `@text()` without `max` generates `NVARCHAR(MAX)` columns on MSSQL.
+- Rayfin's metadata provider may fail to build a GraphQL schema from these columns, resulting in "Internal server error" at runtime after an otherwise successful deploy.
+- Use `@text({ max: N })` on all string fields to avoid this.

package/assets/docs/preview/local-dev-docker.md

@@ -0,0 +1,124 @@
+# Local development with Docker
+
+> **Preview content** — this page is not published in the public docs.
+> To enable Docker-based local development, set `RAYFIN_FEATURE_FLAGS=docker-local-dev`.
+
+## Overview
+
+The `rayfin dev` command provides a Docker Compose–based local development environment.
+It launches containers for enabled services, runs health checks, and auto-applies the database configuration.
+
+Docker and Docker Compose must be installed and running before using this command.
+
+## Starting the environment
+
+```bash
+npx rayfin dev
+```
+
+This command:
+
+- Validates that Docker and Docker Compose are available.
+- Generates `rayfin/.temp/docker-compose.yml` from your project configuration.
+- Allocates ports for each service.
+- Starts containers for enabled services (WebService, database, and optional storage).
+- Runs health checks and waits for all services to be healthy.
+
+Wait for the `All services healthy` message before continuing.
+
+## Stopping and resetting
+
+| Flag | Behavior |
+|------|----------|
+| `--stop` | Stop running containers without removing them |
+| `--down` | Stop and remove containers |
+| `--purge` | Stop, remove containers, and delete volumes (full reset) |
+
+```bash
+npx rayfin dev --stop
+npx rayfin dev --down
+npx rayfin dev --purge
+```
+
+## Additional options
+
+| Flag | Behavior |
+|------|----------|
+| `--detach` | Run containers in the background |
+| `--pull` | Pull latest images before starting |
+| `--verbose` | Show detailed Docker output |
+| `--debug` | Enable debug logging |
+| `--migrate` | Run database migrations on start |
+| `--unsafe` | Skip safety checks (use with caution) |
+
+## Subcommands
+
+### `rayfin dev db apply`
+
+Generate and apply DAB configuration to the local development server.
+
+```bash
+npx rayfin dev db apply
+npx rayfin dev db apply --force
+```
+
+Run this after making changes to entities in `rayfin/data/`.
+Use `--force` to regenerate configuration even if no changes are detected.
+
+### `rayfin dev storage apply`
+
+Generate and apply storage configuration to the local development server.
+
+```bash
+npx rayfin dev storage apply
+```
+
+### `rayfin dev status`
+
+Display the status of the local development environment.
+
+```bash
+npx rayfin dev status
+```
+
+Shows container health, port assignments, and service readiness.
+
+### `rayfin dev watch`
+
+Watch `./rayfin/data` or `./rayfin/storage` and auto-apply configuration changes.
+
+```bash
+npx rayfin dev watch
+```
+
+## Configuration
+
+The `rayfin/rayfin.yml` file controls which services run in the local environment.
+Changes to `rayfin.yml` require restarting the environment:
+
+```bash
+npx rayfin dev --down
+npx rayfin dev
+```
+
+## Troubleshooting
+
+- **Docker not running** — ensure Docker Desktop or the Docker daemon is started.
+- **`rayfin dev db apply` fails** — make sure services are healthy first (`npx rayfin dev status`).
+- **Stale services** — stop stale containers with `npx rayfin dev --down`, then restart.
+- **`unsupported UUID` errors** — stop stale services with `npx rayfin dev --down`.
+- **Port conflicts** — use `npx rayfin dev --purge` for a full reset.
+
+## Enabling this feature
+
+Set the feature flag in your environment:
+
+```bash
+export RAYFIN_FEATURE_FLAGS=docker-local-dev
+```
+
+Or combine with other flags:
+
+```bash
+export RAYFIN_FEATURE_FLAGS=docker-local-dev,storage
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.1.0",
+  "version": "1.33.0-beta.1",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [

package/assets/docs/quickstart.md

@@ -1,81 +0,0 @@
----
-symbols: []
----
-
-# Quickstart
-
-This quickstart walks you through scaffolding a new Rayfin project,
-defining your first entity, running the project locally, and querying
-via GraphQL.
-
-## Prerequisites
-
-- Node.js 20+
-- A modern terminal (PowerShell, bash, zsh)
-
-## 1. Scaffold a new project
-
-```bash
-npm create rayfin@latest my-app
-cd my-app
-npm install
-```
-
-The scaffold creates a Rayfin project with:
-
-- `rayfin/data/` — your entity classes
-- `rayfin.config.json` — project configuration
-- `package.json` with `rayfin-cli`, `rayfin-core`, `rayfin-data`, and
-  `rayfin-auth` already wired
-
-## 2. Define your first entity
-
-Edit `rayfin/data/Todo.ts`:
-
-```typescript
-import { entity, uuid, text, int, anonymous, authenticated } from '@microsoft/rayfin-core';
-
-@entity()
-@anonymous('read')
-@authenticated('*')
-export class Todo {
-  @uuid() id!: string;
-  @text() title!: string;
-  @int() priority!: number;
-  @text({ optional: true }) notes?: string;
-}
-```
-
-## 3. Run locally
-
-```bash
-rayfin up
-```
-
-This generates a DAB-compliant configuration from your entity classes
-and starts the Data API Builder server on
-[http://localhost:5000](http://localhost:5000).
-
-## 4. Query via GraphQL
-
-Open [http://localhost:5000/graphql](http://localhost:5000/graphql) and try:
-
-```graphql
-query {
-  todos {
-    items {
-      id
-      title
-      priority
-    }
-  }
-}
-```
-
-## Next steps
-
-- [Auth overview](./index.md) — for sign-in flows beyond the
-  built-in `anonymous` role.
-- Per-package reference via `rayfin docs list --module ts-sdk`.
-- Deploy to Fabric: see the `rayfin up staticapp deploy` subcommand
-  (interactive scaffolding through Fabric workspace selection).