# satriotsubasa/powerplatform-core architecture

> Architecture diagram of the GitHub repository satriotsubasa/powerplatform-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satriotsubasa/powerplatform-core
- Repository: https://github.com/satriotsubasa/powerplatform-core

## Overview

1. This repository is a **generic Power Platform / Dataverse skill runtime**, not an app. Its purpose is to let an agent inspect an unfamiliar repo, infer structure, and execute repo-backed changes against Dataverse and Power Platform using repeatable helpers instead of portal-first workflows.

2. The **core contract layer** lives in `SKILL.md`, `agents/`, `references/`, and `assets/`. `README.md` makes clear that these files define the skill’s behavior, guidance, and packaging boundaries, while overlay-specific conventions are intentionally excluded from Core.

3. The **main control plane** is the Python script suite in `scripts/`. These entry points cover discovery, auth gating, requirement execution, Dataverse metadata operations, solution deployment, flow inspection/hardening, PCF packaging/deployment, form/XML patching, security-role updates, web resource sync, and validation. In architecture terms, this is the orchestration layer that translates agent intent into repo-aware actions.

4. A key subsystem is **repo discovery and context inference**. `scripts/discover_context.py` is the first-pass classifier for repo shape, and the tests include many fixture repos that model layered hybrids, unpacked solutions, tool-only repos, ambiguous repos, and sparse repos. This means the runtime is designed to select behavior based on repository topology rather than a fixed project template.

5. Another boundary is **authentication and environment targeting**. `scripts/auth_context.*`, `scripts/whoami.py`, and related helpers enforce PAC/environment awareness and selected-solution confirmation before live work. The runtime explicitly tries to surface mismatches between the requested target and the currently selected PAC profile, which is an important safety boundary in the execution flow.

6. The **Dataverse / solution operations layer** is split between metadata design and deployment actions. Scripts such as `create_table.py`, `create_field.py`, `create_lookup.py`, `create_custom_api.py`, `create_security_role.py`, `ensure_dataverse_reference.py`, `set_table_icon.py`, and `add_solution_components.py` represent source-controlled changes to the model, while `deploy_solution.py`, `plan_solution_patch_merge.py`, and `validate_delivery.py` handle packaging, patching, and release safety.

7. The **client customization subsystem** covers form and web-resource surface area. Scripts like `update_main_form.py`, `update_form_events.py`, `patch_form_xml.py`, `patch_form_ribbon.py`, `sync_webresource.py`, `sync_webresources_batch.py`, `bind_pcf_control.py`, and `deploy_pcf.py` show that the runtime treats form XML, script registration, and PCF binding as managed, solution-scoped artifacts.

8. The **server-side extension subsystem** handles plug-ins and custom APIs. `push_plugin.py`, `register_plugin_headless.py`, `register_plugin_package_headless.py`, `ensure_plugin_step_state.py`, and the `create_custom_api.py` helper support repeatable plug-in registration and step-state management. This indicates a boundary between code deployment and Dataverse registration metadata.

9. The **automation subsystem** focuses on cloud flows and related hardening. `create_flow.py`, `inspect_flow.py`, `update_flow.py`, `lint_flow.py`, `get_flow_trigger_url.*`, `review_flow_connectors.py`, and `review_flow_hardening.py` suggest a lifecycle of flow creation, inspection, update, and governance. The repository also includes a flow-guards template and dedicated references for Power Automate design and execution-surface guidance.

10. The **data operations subsystem** is separate from schema design. `upsert_data.py`, `design_dataverse_query.py`, and the data-operation references indicate support for controlled row-level operations, query planning, and provenance-aware updates. The README explicitly notes strong boundaries around stable keys, dry-run honesty, and source-qualified provenance.

11. The **.NET tooling layer** under `tools/` provides heavier implementation where Python wrappers would be awkward. `CodexPowerPlatform.DataverseOps` contains the main CLI-style engine for metadata operations, including forms, layouts, PCF, environment variables, plugins, security roles, web resources, and patching. `CodexPowerPlatform.AuthDialog` is a WPF desktop helper for interactive auth/selection workflows. A dedicated test project validates the form XML patch engine.

12. The **test suite** is not just unit coverage; it encodes the repository’s architectural assumptions. `tests/test_discover_context.py` and the fixture tree verify repo-shape inference, while other tests cover deployment safety, semantic flow guards, delivery validation, patch helpers, and skill acceptance scenarios. This gives the runtime a regression harness for its orchestration and safety rules.

13. The **documentation/reference layer** is intentionally broad and modular. Files in `references/` describe execution surfaces, context and ALM, custom connectors, Dataverse metadata, document generation, solution standards, security roles, helper strategy, and recovery/verification. These documents function as policy and decision boundaries for how the scripts should behave, rather than as product documentation.

14. The overall data flow is: a user request enters the skill contract, the runtime discovers repo shape and context, auth/target checks gate any live action, helpers update source artifacts or Dataverse state, and validation scripts confirm outcomes. The explicit architectural split is between **source-controlled repo changes**, **headless Dataverse/Power Platform execution**, and **verification/repair**, with overlays allowed to extend the generic Core without changing its base contract.

Main entry points: [`scripts/apply_requirement_spec.py`](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/apply_requirement_spec.py) (Requirements), [`scripts/deploy_solution.py`](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/deploy_solution.py) (Solution ops), [`tools/CodexPowerPlatform.DataverseOps`](https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.DataverseOps) (DataverseOps), [`tests`](https://github.com/satriotsubasa/powerplatform-core/tree/main/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core contract"]
  node_skill_md["SKILL.md<br/>skill contract<br/>[SKILL.md]"]
  node_agents["Agents<br/>agent config"]
  node_assets["Assets"]
end

subgraph group_runtime["Python runtime"]
  node_discover_context["Discover context<br/>repo classifier"]
  node_auth_context["Auth context<br/>auth gate<br/>[auth_context.py]"]
  node_whoami["Who am I<br/>environment check<br/>[whoami.py]"]
  node_requirement_flow["Requirements<br/>task runner"]
  node_metadata_ops["Metadata ops<br/>schema tools<br/>[create_table.py]"]
  node_solution_ops["Solution ops<br/>packaging flow<br/>[deploy_solution.py]"]
  node_client_customization["Client customizations<br/>ui surface tools"]
  node_pcf_ops["PCF tools<br/>pcf pipeline"]
  node_plugin_ops["Plugins<br/>server extension tools<br/>[push_plugin.py]"]
  node_flow_ops["Flows<br/>automation tools<br/>[create_flow.py]"]
  node_data_ops["Data ops<br/>row-level tools<br/>[upsert_data.py]"]
end

subgraph group_dotnet[".NET tooling"]
  node_dotnet_ops["DataverseOps<br/>dotnet cli"]
  node_auth_dialog["Auth dialog<br/>desktop helper"]
end

subgraph group_quality["Validation"]
  node_dotnet_tests["Dotnet tests<br/>engine tests"]
  node_tests["Tests<br/>regression suite"]
end

subgraph group_docs["References"]
  node_references["References<br/>policy docs"]
end

node_skill_md -->|"defines"| node_agents
node_skill_md -->|"bounded by"| node_references
node_skill_md -->|"packages"| node_assets
node_discover_context -->|"gates"| node_auth_context
node_auth_context -->|"verifies"| node_whoami
node_discover_context -->|"selects"| node_requirement_flow
node_requirement_flow -->|"drives"| node_metadata_ops
node_requirement_flow -->|"drives"| node_client_customization
node_requirement_flow -->|"drives"| node_plugin_ops
node_requirement_flow -->|"drives"| node_flow_ops
node_requirement_flow -->|"drives"| node_data_ops
node_solution_ops -->|"packages"| node_metadata_ops
node_solution_ops -->|"packages"| node_pcf_ops
node_solution_ops -->|"packages"| node_client_customization
node_solution_ops -->|"packages"| node_plugin_ops
node_solution_ops -->|"packages"| node_flow_ops
node_dotnet_ops -->|"implements"| node_metadata_ops
node_dotnet_ops -->|"implements"| node_client_customization
node_dotnet_ops -->|"implements"| node_pcf_ops
node_dotnet_ops -->|"implements"| node_plugin_ops
node_dotnet_ops -->|"implements"| node_flow_ops
node_auth_dialog -->|"supports"| node_auth_context
node_tests -->|"covers"| node_discover_context
node_tests -->|"covers"| node_solution_ops
node_tests -->|"covers"| node_flow_ops
node_tests -->|"covers"| node_pcf_ops
node_tests -->|"covers"| node_data_ops
node_dotnet_tests -->|"covers"| node_dotnet_ops

click node_skill_md "https://github.com/satriotsubasa/powerplatform-core/blob/main/SKILL.md"
click node_agents "https://github.com/satriotsubasa/powerplatform-core/tree/main/agents"
click node_references "https://github.com/satriotsubasa/powerplatform-core/tree/main/references"
click node_assets "https://github.com/satriotsubasa/powerplatform-core/tree/main/assets"
click node_discover_context "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/discover_context.py"
click node_auth_context "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/auth_context.py"
click node_whoami "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/whoami.py"
click node_requirement_flow "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/apply_requirement_spec.py"
click node_metadata_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/create_table.py"
click node_solution_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/deploy_solution.py"
click node_client_customization "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/update_main_form.py"
click node_pcf_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/scaffold_pcf_control.py"
click node_plugin_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/push_plugin.py"
click node_flow_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/create_flow.py"
click node_data_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/upsert_data.py"
click node_dotnet_ops "https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.DataverseOps"
click node_auth_dialog "https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.AuthDialog"
click node_dotnet_tests "https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.DataverseOps.Tests"
click node_tests "https://github.com/satriotsubasa/powerplatform-core/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_md,node_agents,node_assets toneBlue
class node_discover_context,node_auth_context,node_whoami,node_requirement_flow,node_metadata_ops,node_solution_ops,node_client_customization,node_pcf_ops,node_plugin_ops,node_flow_ops,node_data_ops toneAmber
class node_dotnet_ops,node_auth_dialog toneMint
class node_dotnet_tests,node_tests toneRose
class node_references toneIndigo
```

## Components

### Core contract

Skill behavior, guidance, and packaging boundaries.

- [SKILL.md](https://github.com/satriotsubasa/powerplatform-core/blob/main/SKILL.md): skill contract · Primary skill contract and operating rules. · `SKILL.md`
- [Agents](https://github.com/satriotsubasa/powerplatform-core/tree/main/agents): agent config · Agent-specific guidance and behavior overlays. · `agents`
- [Assets](https://github.com/satriotsubasa/powerplatform-core/tree/main/assets): packaged assets · Bundled skill assets and supporting content. · `assets`

### Python runtime

Discovery, gating, orchestration, and repo-backed operations.

- [Discover context](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/discover_context.py): repo classifier · Infers repo shape and execution mode from filesystem topology. · `scripts/discover_context.py`
- [Auth context](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/auth_context.py): auth gate · Checks PAC profile, environment targeting, and selected-solution safety. · `scripts/auth_context.py`
- [Who am I](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/whoami.py): environment check · Reports the active Dataverse/PAC identity and target state. · `scripts/whoami.py`
- [Requirements](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/apply_requirement_spec.py): task runner · Applies requirement specs into repeatable repo-backed actions. · `scripts/apply_requirement_spec.py`
- [Metadata ops](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/create_table.py): schema tools · Creates and updates tables, fields, lookups, custom APIs, icons, and related metadata. · `scripts/create_table.py`
- [Solution ops](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/deploy_solution.py): packaging flow · Adds components, versions, patches, merges, deployment, and delivery validation. · `scripts/deploy_solution.py`
- [Client customizations](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/update_main_form.py): ui surface tools · Main forms, form events, ribbon XML, views, and web resources. · `scripts/update_main_form.py`
- [PCF tools](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/scaffold_pcf_control.py): pcf pipeline · Scaffolds, binds, versions, and deploys PCF controls. · `scripts/scaffold_pcf_control.py`
- [Plugins](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/push_plugin.py): server extension tools · Pushes, registers, and inspects plug-in assemblies and step state. · `scripts/push_plugin.py`
- [Flows](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/create_flow.py): automation tools · Creates, inspects, updates, lints, and hardens Power Automate flows. · `scripts/create_flow.py`
- [Data ops](https://github.com/satriotsubasa/powerplatform-core/blob/main/scripts/upsert_data.py): row-level tools · Controlled upsert, query design, and provenance-aware data operations. · `scripts/upsert_data.py`

### .NET tooling

Heavier Dataverse and auth helpers used by the Python wrappers.

- [DataverseOps](https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.DataverseOps): dotnet cli · Main .NET engine for metadata, forms, PCF, plugins, flows, and patching. · `tools/CodexPowerPlatform.DataverseOps`
- [Auth dialog](https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.AuthDialog): desktop helper · WPF helper for interactive auth and solution/target selection. · `tools/CodexPowerPlatform.AuthDialog`

### Validation

Tests and safety checks that encode the repository’s operating rules.

- [Dotnet tests](https://github.com/satriotsubasa/powerplatform-core/blob/main/tools/CodexPowerPlatform.DataverseOps.Tests): engine tests · Validates the form XML patch engine and related .NET behavior. · `tools/CodexPowerPlatform.DataverseOps.Tests`
- [Tests](https://github.com/satriotsubasa/powerplatform-core/tree/main/tests): regression suite · Repository-shape inference, safety rules, flow guards, delivery validation, and acceptance scenarios. · `tests`

### References

Policy and guidance documents for execution and customization.

- [References](https://github.com/satriotsubasa/powerplatform-core/tree/main/references): policy docs · Repository guidance for Dataverse, flows, ALM, security, and recovery. · `references`

## Connections

- SKILL.md → Agents: defines · Skill contract informs agent behavior.
- SKILL.md → References: bounded by · References provide operating guidance and policy boundaries.
- SKILL.md → Assets: packages · Skill packaging includes assets and bundled support files.
- Discover context → Auth context: gates · Repo classification precedes target and auth checks.
- Auth context → Who am I: verifies · Identity and environment state are confirmed before live actions.
- Discover context → Requirements: selects · Repository shape influences which requirement workflow runs.
- Requirements → Metadata ops: drives · Requirement execution may create or update Dataverse schema.
- Requirements → Client customizations: drives · Requirements can patch forms, views, ribbons, and web resources.
- Requirements → Plugins: drives · Requirements can register and update server-side extensions.
- Requirements → Flows: drives · Requirements can create, inspect, and harden cloud flows.
- Requirements → Data ops: drives · Requirements can perform controlled row-level data operations.
- Solution ops → Metadata ops: packages · Metadata changes flow into solution assembly and deployment.
- Solution ops → PCF tools: packages · PCF artifacts are versioned and deployed through solutions.
- Solution ops → Client customizations: packages · Client-side artifacts are solution-scoped and deployment-bound.
- Solution ops → Plugins: packages · Plug-in artifacts are bundled into solution delivery.
- Solution ops → Flows: packages · Flow assets are validated and delivered with solution governance.
- DataverseOps → Metadata ops: implements · .NET engine provides deeper metadata and patching operations.
- DataverseOps → Client customizations: implements · Supports forms, layouts, web resources, and XML patching.
- DataverseOps → PCF tools: implements · Supports PCF packaging and deployment mechanics.
- DataverseOps → Plugins: implements · Supports plug-in registration and step-state handling.
- DataverseOps → Flows: implements · Supports flow and automation operations.
- Auth dialog → Auth context: supports · Interactive selection helper backs authentication workflows.
- Tests → Discover context: covers · Fixture repos validate topology inference.
- Tests → Solution ops: covers · Safety and delivery validation are regression tested.
- Tests → Flows: covers · Flow semantic guards and delivery helpers are validated.
- Tests → PCF tools: covers · PCF deployment and versioning behavior is tested.
- Tests → Data ops: covers · Query and data-operation behavior is tested.
- Dotnet tests → DataverseOps: covers · Engine-level tests validate the patch engine and related behavior.
