integrate-backend

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# Backend Integration

Analyze the user's business problem and recommend the right backend integration approach — **Web API**, **AI Web API**, **Server Logic**, **Cloud Flows**, or a combination — then route to the appropriate skill(s) to implement the solution.

## Core Principles

- **Understand the problem first**: Never jump to a technology choice. Analyze the user's intent, data flow, security needs, and performance requirements before recommending.
- **Recommend the simplest approach that works**: Web API for straightforward Dataverse CRUD, AI Web API for generative summaries or grounded search over existing data, Server Logic when server-side processing is needed, Cloud Flows for async background work. Don't over-engineer.
- **Secure actions belong on the server**: When a write depends on a business rule that must be tamper-proof (state transitions, approval workflows, computed values), the server logic must validate AND execute the write — not just validate and leave the write to a client-side Web API call. See the **Secure Action Principle** in the decision framework.
- **AI Web API sits on top of Web API**: The Data Summarization and Case-preset endpoints read through the same `_api` layer as regular Web API, so they inherit the same table permissions, column permissions, and `Webapi/<table>/*` site settings. When a plan has both a Web API item and an AI Web API item for the same table, the AI item depends on (and goes in a later phase than) the Web API item. Search Summary has no per-table prereqs and can stand alone.
- **Combinations are normal**: Many real scenarios need more than one approach. Recommend combinations when justified, but explain why each piece is needed.
- **Route, don't implement**: This skill recommends and invokes the right skill(s). It does not create backend files itself.

**Initial request:** $ARGUMENTS

---

## Workflow

1. **Verify Site Exists** — Locate the Power Pages project and check prerequisites
2. **Understand the Business Problem** — Analyze what the user needs and why
3. **Recommend Integration Approach** — Present the recommendation with reasoning
4. **Route to Skill(s)** — Invoke the appropriate backend skill(s) to implement

---

## Phase 1: Verify Site Exists

**Goal**: Locate the Power Pages project root and confirm prerequisites

**Actions**:

1. Create todo list with all 4 phases (see [Progress Tracking](#progress-tracking) table)

### 1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories.

**If not found**: Tell the user to create a site first with `/create-site`.

### 1.2 Explore Current State

Use the **Explore agent** to quickly scan the site for existing backend integrations:

> "Analyze this Power Pages code site for existing backend integrations:
> 1. Check `.powerpages-site/server-logic/` — list any existing server logic endpoints
> 2. Check `.powerpages-site/cloud-flow-consumer/` — list any registered cloud flows
> 3. Search frontend code (`src/**/*.{ts,tsx,js,jsx,vue,astro}`) for calls to `/_api/` (Web API) and `/_api/serverlogics/` (Server Logic) and `/_api/cloudflow/` (Cloud Flows)
> 4. Check for existing service layers or API utilities in `src/services/`, `src/shared/`, or similar
> 5. List available web roles from `.powerpages-site/web-roles/*.webrole.yml`
> Report what backend integrations already exist so we can build on them."

### 1.3 Discover Dataverse Custom Actions

Check whether the user's Dataverse environment has existing custom actions that could be leveraged in the integration:

```bash
node "${PLUGIN_ROOT}/scripts/list-custom-actions.js" "<ENV_URL>"
```

The script returns Custom APIs (modern) and Custom Process Actions (legacy) with their names, descriptions, binding types, and parameters. If custom actions are found, note them — they will be factored into the recommendation in Phase 3.

**Output**: Project root confirmed, existing backend integrations identified, Dataverse custom actions discovered

---

## Phase 2: Understand the Business Problem

**Goal**: Analyze the user's request to understand the underlying business problem, not just the technical ask

**Actions**:

### 2.1 Analyze the Request

From the user's request and the existing site state, determine:

- **What is the user trying to accomplish?** (business outcome, not technology)
- **What data is involved?** (Dataverse tables, external systems, user input)
- **Who triggers the operation?** (user action, form submit, page load, scheduled)
- **Does the user need an immediate response?** (real-time UI update vs. background processing)
- **Are external services involved?** (payment gateways, email, Graph, SharePoint, third-party APIs)
- **Are credentials or secrets involved?** (API keys, client secrets, tokens)
- **Must logic be hidden from the browser?** (pricing rules, validation algorithms, business rules)
- **Is this a simple data operation or complex business logic?** (CRUD vs. multi-step processing)
- **Does any write depend on a business rule that must be tamper-proof?** (state transitions, approval conditions, computed values) — if yes, the server logic must validate AND execute the write, not just validate
- **Does the UI want an AI-generated summary, grounded AI search, or related-record discovery?** (e.g., "summarize this case", "summarize open orders", "suggest KB articles on the case page", "AI-powered search") — if yes, AI Web API is the right fit. Watch for the phrasing signals: *summarize*, *summary of*, *Copilot*, *related / similar / suggested <entity>*, *AI search*, *semantic search*.
- **Can existing Dataverse custom actions handle part of the requirement?** If custom actions were discovered in Phase 1.3, check whether any align with the user's needs — server logic can wrap existing custom actions via `InvokeCustomApi` instead of building