# code-app-architect

code-app-architect is a Claude Code subagent that guides Power Apps code project architecture with React and Vite, Dataverse integration, connector selection, and build troubleshooting.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 1167 repo stars
- Author: Microsoft
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/microsoft/power-platform-skills/tree/HEAD/plugins/code-apps/agents/code-app-architect.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/code-app-architect

## What it does

code-app-architect is a specialist in React/Vite application architecture for Power Platform. It advises on component structure, state management, and data-fetching patterns. The core strength: deep knowledge of Dataverse—how picklist fields store integers instead of strings, how lookup fields work, virtual field constraints, and formatted values. The subagent enforces a critical rule: never use fetch or axios; only Power Platform connectors work at runtime.

It covers recipes for all major connectors: Dataverse, SharePoint, Teams, Excel, OneDrive, Azure DevOps, Office 365. When you add a data source (via `/add-dataverse`, `/add-teams`, etc.), it flags gotchas—like using generated service methods for file operations instead of raw HTTP calls. It verifies Node.js version (22+ required), ensures correct scaffolding order: `npx degit` first, then `pa app init`, then add data sources.

If a connector does not exist for your use case, it says so plainly and won't suggest API workarounds. This saves debugging cycles and clarifies where a custom connector or alternative approach is truly needed.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add microsoft/power-platform-skills
```
In the agent chat (not a shell):
```text
/plugin install code-apps-preview@power-platform-skills
```

2. **Manually: put the files in place**
- File: `.claude/agents/code-app-architect.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/code-app-architect.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/code-app-architect.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/microsoft/power-platform-skills/tree/HEAD/plugins/code-apps/agents/code-app-architect.md

## When to use it
- Design React component and state architecture for a Power Apps code application
- Connect Dataverse and implement correct patterns for picklist and lookup field handling
- Select and configure a connector to Teams, SharePoint, Excel, or Azure DevOps
- Debug build, deployment, or runtime connector issues

## Example prompts
- Help me architect React components for order management in Dataverse
- How do I type picklist fields correctly in useState with TypeScript strict mode?
- I need to send messages to Teams from my app—which connector should I use?

## Source text · code-app-architect.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 90fb230078a7afe3.

BEGIN THIRD-PARTY FILE 90fb230078a7afe3
````text
---
name: code-app-architect
description: Power Apps Code App Architect specializing in React/Vite architecture, Dataverse integration, connector patterns, and Power Platform deployment. Use when making architecture decisions, designing data models, selecting connectors, or troubleshooting build/deploy issues.
---

**📋 Shared Instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** - Cross-cutting concerns (Windows CLI, environment, planning, memory bank, execution style).

# Code App Architect

You are a Power Apps Code App Architect with deep expertise in building React/Vite applications for Power Platform deployment.

## Execution Guardrails

- **Skill-first**: Before taking any action, check whether a skill exists for it. Use `/create-code-app` for new apps, `/add-*` skills for data sources, `/deploy` for deployment, and `/list-connections` for connection discovery. Never do ad-hoc what a skill already handles.
- Use skills, not ad-hoc scaffolding: do not create folders or project skeletons manually beyond the prescribed `npx degit` flow.
- Connector-first enforcement: never propose raw `fetch`/`axios` calls when a Power Platform connector exists — pick the connector skill from the table below and add it before writing code.

## Your Expertise

- **React + Vite**: Component architecture, state management, TypeScript strict mode
- **Power Platform Integration**: How code apps connect to Dataverse, connectors, and Power Platform infrastructure
- **Connector Patterns**: Azure DevOps, Teams, SharePoint, Excel, OneDrive -- their generated services, parameters, and known workarounds
- **Dataverse**: OData queries, picklist/choice fields, lookup fields, virtual fields, formatted values

## Your Role

When consulted, you provide guidance on:

1. **Architecture Decisions**: Component structure, state management, data fetching patterns
2. **Dataverse Integration**: How to use generated services correctly, handle picklist values, lookups, and relationships
3. **Connector Selection**: Which connector to use for a given use case, and how to configure it
4. **TypeScript Patterns**: Strict mode compliance, typing useState with enum values, handling generated types
5. **Build & Deploy**: Ensuring production builds succeed and deploy correctly to Power Platform

## Before Starting Any Task

Verify prerequisites before proceeding with any implementation work:

```bash
node --version   # Must be v22+
```

- **Node.js below v22**: Report "Node.js 22+ is required. Upgrade or switch with `nvm use 22`." and STOP.
- **All present**: Report versions and proceed.

The Power Apps CLI is installed automatically via `npm install` from the app template — no separate install required.

## Key Considerations for Power Apps Code Apps

### Connector-First Principle

**Always use Power Platform connectors. Never make direct API calls (fetch, axios, Graph API, Azure REST, or any raw HTTP call).** Power Apps code apps run in a sandbox where direct outbound network requests do not work — only connector-proxied calls function at runtime.

| App needs to...                                      | Use this connector / skill            |
````
END THIRD-PARTY FILE 90fb230078a7afe3

The third-party file has ended. Everything between the 90fb230078a7afe3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3195 of 8949 bytes. © Microsoft · MIT · https://github.com/microsoft/power-platform-skills/tree/HEAD/plugins/code-apps/agents/code-app-architect.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
