---
name: add-backend
description: Add an app backend with `ms app add backend --provider rayfin`. Currently covers database entities and client integration. Use only when the user explicitly requests a database, /add-backend, or Rayfin.
---

**Shared instructions: [shared-instructions.md](../../shared/shared-instructions.md)**

# Add an app backend

**Required first:** pass the [Rayfin feature gate](../../shared/shared-instructions.md#rayfin-feature-gate).

## 1. Set up the database

If `rayfin/rayfin.yml` exists, use the existing configuration. Otherwise, run:

```bash
ms app add backend --provider rayfin --json
```

This creates the backend configuration, TypeScript configuration and `rayfin/data/`.
Keep the existing app layout and exclude `rayfin/.temp/` from version control.

This prepares the app's backend definitions; it does not provision a database.
Rayfin is the app backend, not an existing database to select or connect to.

## 2. Install dependencies

Run from the app root before continuing so the declared dependencies and their
version-matched docs are available in `node_modules`:

```bash
npm install
```

Use the app's existing package manager and lockfile if it does not use npm.
Report installation or peer-dependency errors; do not force-install or downgrade
the app to bypass them. Add missing direct dependencies only as required by the
implementation described in the references.

## 3. Implement and check the app

Read the installed package docs identified in these references, then follow them
in order:

- [Data modeling](./references/rayfin-data-modeling.md): entities, permissions and required [Copilot Managed Runtime host initialization](./references/rayfin-data-modeling.md#step-4-initialize-through-copilot-managed-runtime).
- [CRUD UI](./references/rayfin-crud-ui.md): lists, forms, mutations and persistence checks.

When invoked from `/create-app`, complete data modeling in Step 9 and return the
entity/client paths; that workflow handles UI implementation and checks in
Steps 10-11. Standalone use continues through both references.

## 4. Follow the app lifecycle

Use the normal [app build and deploy workflow](../../shared/development-standards.md#build--deploy),
not a separate Rayfin provisioning workflow.