Restructure samples into category-first taxonomy (apps / snippets / traditional / server-logic)

CONTRIBUTING.md

@@ -12,3 +12,28 @@ instructions provided by the bot. You will only need to do this once across all
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
 or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Repository layout
+
+Samples live under `samples/`, grouped by how they are delivered to Power Pages:
+
+- **`spa/`** — code sites (single-page apps) built with a frontend framework and uploaded with the Power Platform CLI, split into two kinds:
+  - **`spa/apps/<name>/<framework>/`** — full, multi-feature reference applications. Apps always keep a framework subfolder (e.g. `car-sales-website/react/`, `car-sales-website/angular/`) so multiple ports of the same app sit side by side.
+  - **`spa/snippets/<topic>/`** — small, single-topic samples that each teach one capability. Snippets are React-only, so the framework subfolder is omitted and the React app sits directly under the topic folder.
+  - **`spa/snippets/<topic>/<variant>/`** — a snippet family: several variants of one topic, each its own React app, with a parent `README.md` that indexes them. Variants are still React-only and still have no framework subfolder. See `spa/snippets/file-upload/` (with `notes/`, `file-column/`, `sharepoint/`, `azure-blob/` variants) as the reference.
+- **`traditional/<name>/`** — non-code sites built with Liquid and web templates on the enhanced data model.
+- **`server-logic/<name>/`** — server-side JavaScript that runs on the Power Pages runtime and can be called from both code sites and traditional sites.
+
+### Where does my sample go?
+
+- Teaches **one** capability and ships as a single React app → **`spa/snippets/`**. It stays a snippet even if it is polished — teaching one thing is what makes it a snippet.
+- Shows several variants of one topic (e.g. "N ways to upload a file") → **`spa/snippets/<topic>/<variant>/`** with a parent index README.
+- A **full, multi-feature** application → **`spa/apps/`**. As an objective test, choose `apps/` when the sample has **multiple routes/pages _and_ touches more than one Dataverse table or feature area**, or when it ships **more than one framework port**.
+- A **non-code** (Liquid / web template) site → **`traditional/`**.
+- A reusable **server-side** function → **`server-logic/`**.
+
+**Snippet → app graduation:** a snippet becomes an app when it grows a second framework port (e.g. an Angular or Vue version is added). At that point, move it from `spa/snippets/<topic>/` to `spa/apps/<name>/<framework>/` so every port shares one parent. Apps are named with a `-website` or `-template` suffix (e.g. `car-sales-website`, `vue-admin-template`), so rename the topic folder accordingly on graduation (a `payments` snippet becomes `apps/payments-website/react/`, not `apps/payments/react/`).
+
+**Server logic → `extensions/` graduation:** `server-logic/` is currently a top-level category because it is the only runtime-feature sample. When a **second, different** runtime-feature category is needed (for example a non-server-logic runtime extension), introduce a shared parent `extensions/` and move `server-logic/` under it (`extensions/server-logic/`) at that point — do not add the new feature as another top-level peer.
+
+When adding a sample, follow the structure and README conventions of an existing sample in the same category (README with setup steps, deployment notes, and a `screenshot.png`).

MIGRATION.md

@@ -0,0 +1,37 @@
+# Migration guide — samples reorganized
+
+The `samples/` folder was reorganized (July 2026) from a **framework-first**
+layout (`samples/spa/react/…`, `samples/spa/angular/…`, `samples/spa/vue/…`) to a
+**category-first** layout:
+
+- `spa/apps/` — full, multi-feature reference applications (`<name>/<framework>/`)
+- `spa/snippets/` — single-topic samples (React-only, flat)
+- `traditional/` — non-code Liquid / web-template sites
+- `server-logic/` — server-side runtime code
+
+GitHub does **not** redirect renamed paths, so links that pointed at the old
+locations now return 404. Use the table below to find where a sample moved.
+
+## Moved paths (old → new)
+
+| Sample | Old path (before reorg) | New path |
+| --- | --- | --- |
+| Car Sales Website (React) | `samples/spa/react/car-sales-website/` | `samples/spa/apps/car-sales-website/react/` |
+| Car Sales Website (Angular) | `samples/spa/angular/car-sales-website/` | `samples/spa/apps/car-sales-website/angular/` |
+| Credit Cards Website (React) | `samples/spa/react/credit-cards-website/` | `samples/spa/apps/credit-cards-website/react/` |
+| Vue Admin Template (Vue) | `samples/spa/vue/vue-admin-template/` | `samples/spa/apps/vue-admin-template/vue/` |
+| Environment Variables | `samples/spa/react/environment-variables-samples/vite-framework/` | `samples/spa/snippets/environment-variables/` |
+| Fluent UI | `samples/spa/react/fluent-ui-sample/` | `samples/spa/snippets/fluent-ui/` |
+| Localization | `samples/spa/react/localization-sample/` | `samples/spa/snippets/localization/` |
+| Authentication | `samples/spa/react/authentication-sample/` | `samples/spa/snippets/authentication/` |
+| Cloud Flow | `samples/spa/react/cloud-flow-sample/` | `samples/spa/snippets/cloud-flow/` |
+| File Upload (all variants) | `samples/spa/react/file-upload/` | `samples/spa/snippets/file-upload/` |
+| SharePoint server logic | `samples/server-logic/sharepoint-integration/` | _(unchanged)_ |
+
+> Some folders were also renamed during the move (for example
+> `environment-variables-samples/vite-framework` → `environment-variables`, and the
+> `-sample` suffixes were dropped), so the new name may not match the old one
+> exactly — use the table rather than guessing.
+
+For how the categories are organized going forward, see
+[CONTRIBUTING.md](CONTRIBUTING.md).

README.md

@@ -4,27 +4,61 @@ This repository contains sample code sites for Microsoft Power Pages. Use the ta
 
 Each sample includes its own README with setup steps, deployment notes, and a screenshot so you can preview the experience before running it locally.
 
+> **Reorganized July 2026.** The `samples/` folder moved from a framework-first to a category-first layout. If you followed an older link, see [MIGRATION.md](MIGRATION.md) for old → new paths.
+
 ## Samples at a glance
 
+Samples are organized under `samples/`:
+
+- **`spa/apps/`** — full, multi-feature reference applications.
+- **`spa/snippets/`** — small, single-topic samples that each teach one capability.
+- **`traditional/`** — non-code sites built with Liquid and web templates on the enhanced data model.
+- **`server-logic/`** — server-side JavaScript that runs on the Power Pages runtime, callable from both code sites and traditional sites.
+
+### Full applications (`samples/spa/apps/`)
+
+| Preview | Sample | Framework | Use this sample to learn |
+| --- | --- | --- | --- |
+| <img src="samples/spa/apps/car-sales-website/react/screenshot.png" alt="React car sales dashboard screenshot" width="180" /> | [Car Sales Website](samples/spa/apps/car-sales-website/react/) | React + Vite | Build a dashboard-style code site with authentication, web roles, virtual tables, and Power Pages Web API integration. |
+| <img src="samples/spa/apps/car-sales-website/angular/screenshot.png" alt="Angular car sales dashboard screenshot" width="180" /> | [Car Sales Website](samples/spa/apps/car-sales-website/angular/) | Angular | Use Angular CLI to build and upload a Power Pages code site based on the car sales scenario. |
+| <img src="samples/spa/apps/credit-cards-website/react/screenshot.png" alt="Woodgrove Bank credit cards website screenshot" width="180" /> | [Credit Cards Website](samples/spa/apps/credit-cards-website/react/) | React + Vite | Create a customer-facing banking site with card browsing, applications, reviewer workflows, authentication, authorization, and Web API calls. |
+| <img src="samples/spa/apps/vue-admin-template/vue/screenshot.png" alt="Vue admin template screenshot" width="180" /> | [Vue Admin Template](samples/spa/apps/vue-admin-template/vue/) | Vue + Vite | Start from a Vue 3 admin-style template that can be uploaded as a Power Pages code site. |
+
+### Single-topic snippets (`samples/spa/snippets/`)
+
 | Preview | Sample | Framework | Use this sample to learn |
 | --- | --- | --- | --- |
-| <img src="samples/spa/react/car-sales-website/screenshot.png" alt="React car sales dashboard screenshot" width="180" /> | [Car Sales Website](samples/spa/react/car-sales-website/) | React + Vite | Build a dashboard-style code site with authentication, web roles, virtual tables, and Power Pages Web API integration. |
-| <img src="samples/spa/angular/car-sales-website/screenshot.png" alt="Angular car sales dashboard screenshot" width="180" /> | [Car Sales Website](samples/spa/angular/car-sales-website/) | Angular | Use Angular CLI to build and upload a Power Pages code site based on the car sales scenario. |
-| <img src="samples/spa/react/credit-cards-website/screenshot.png" alt="Woodgrove Bank credit cards website screenshot" width="180" /> | [Credit Cards Website](samples/spa/react/credit-cards-website/) | React + Vite | Create a customer-facing banking site with card browsing, applications, reviewer workflows, authentication, authorization, and Web API calls. |
-| <img src="samples/spa/react/environment-variables-samples/vite-framework/screenshot.png" alt="Vite React environment variables sample screenshot" width="180" /> | [Environment Variables Demo](samples/spa/react/environment-variables-samples/vite-framework/) | React + Vite | Understand how Vite exposes client-safe environment variables and compile-time constants. |
-| <img src="samples/spa/react/fluent-ui-sample/screenshot.png" alt="Bank loan application portal screenshot" width="180" /> | [Fluent UI Bank Loan Application](samples/spa/react/fluent-ui-sample/) | React + Fluent UI | Build a form-driven portal using Fluent UI v9 controls, state management, and a dashboard-style data grid. |
-| <img src="samples/spa/react/localization-sample/screenshot.png" alt="Contoso Blogs localization sample screenshot" width="180" /> | [Localization Sample](samples/spa/react/localization-sample/) | React + i18next | Add multilingual content, language switching, and localization patterns to a Power Pages code site. |
-| <img src="samples/spa/react/authentication-sample/screenshot.png" alt="Authentication sample burger website screenshot" width="180" /> | [Authentication Sample](samples/spa/react/authentication-sample/) | React + Vite | Explore local sign-in, registration, password reset, invitation redemption, external sign-in, terms acceptance, and role-protected content. |
-| <img src="samples/spa/vue/vue-admin-template/screenshot.png" alt="Vue admin template screenshot" width="180" /> | [Vue Admin Template](samples/spa/vue/vue-admin-template/) | Vue + Vite | Start from a Vue 3 admin-style template that can be uploaded as a Power Pages code site. |
-| <img src="samples/spa/react/cloud-flow-sample/screenshot.png" alt="Cloud flow sample screenshot" width="180" /> | [Cloud Flow Sample](samples/spa/react/cloud-flow-sample/) | React + Vite | Invoke a registered Power Automate cloud flow from a code site with the CSRF token, and render its response. |
-| <img src="samples/spa/react/file-upload/notes/screenshot.png" alt="File upload sample screenshot" width="180" /> | [File Upload (Notes) Sample](samples/spa/react/file-upload/notes/) | React + Vite | Upload, list, download, and delete files via the Web API, stored as Dataverse notes (annotations). |
-| <img src="samples/spa/react/file-upload/file-column/screenshot.png" alt="File upload file column sample screenshot" width="180" /> | [File Upload (File Column) Sample](samples/spa/react/file-upload/file-column/) | React + Vite | Upload, list, download, and delete files via the Web API, stored in a native Dataverse File column (binary, no base64). |
-| <img src="samples/spa/react/file-upload/sharepoint/screenshot.png" alt="SharePoint file upload sample screenshot" width="180" /> | [File Upload (SharePoint) Sample](samples/spa/react/file-upload/sharepoint/) | React + Vite | Upload, list, download, and delete files in a SharePoint document library, reached from a code site through server logic and Microsoft Graph. |
-| <img src="samples/spa/react/file-upload/azure-blob/screenshot.png" alt="Azure Blob file upload sample screenshot" width="180" /> | [File Upload (Azure Blob) Sample](samples/spa/react/file-upload/azure-blob/) | React + Vite | Upload, list, download, and delete files via the Web API, stored in your own Azure Blob container (chunked uploads, up to 10 GB). |
+| <img src="samples/spa/snippets/environment-variables/screenshot.png" alt="Vite React environment variables sample screenshot" width="180" /> | [Environment Variables Demo](samples/spa/snippets/environment-variables/) | React + Vite | Understand how Vite exposes client-safe environment variables and compile-time constants. |
+| <img src="samples/spa/snippets/fluent-ui/screenshot.png" alt="Bank loan application portal screenshot" width="180" /> | [Fluent UI Bank Loan Application](samples/spa/snippets/fluent-ui/) | React + Fluent UI | Build a form-driven portal using Fluent UI v9 controls, state management, and a dashboard-style data grid. |
+| <img src="samples/spa/snippets/localization/screenshot.png" alt="Contoso Blogs localization sample screenshot" width="180" /> | [Localization Sample](samples/spa/snippets/localization/) | React + i18next | Add multilingual content, language switching, and localization patterns to a Power Pages code site. |
+| <img src="samples/spa/snippets/authentication/screenshot.png" alt="Authentication sample burger website screenshot" width="180" /> | [Authentication Sample](samples/spa/snippets/authentication/) | React + Vite | Explore local sign-in, registration, password reset, invitation redemption, external sign-in, terms acceptance, and role-protected content. |
+| <img src="samples/spa/snippets/cloud-flow/screenshot.png" alt="Cloud flow sample screenshot" width="180" /> | [Cloud Flow Sample](samples/spa/snippets/cloud-flow/) | React + Vite | Invoke a registered Power Automate cloud flow from a code site with the CSRF token, and render its response. |
+| <img src="samples/spa/snippets/file-upload/notes/screenshot.png" alt="File upload sample screenshot" width="180" /> | [File Upload (Notes) Sample](samples/spa/snippets/file-upload/notes/) | React + Vite | Upload, list, download, and delete files via the Web API, stored as Dataverse notes (annotations). |
+| <img src="samples/spa/snippets/file-upload/file-column/screenshot.png" alt="File upload file column sample screenshot" width="180" /> | [File Upload (File Column) Sample](samples/spa/snippets/file-upload/file-column/) | React + Vite | Upload, list, download, and delete files via the Web API, stored in a native Dataverse File column (binary, no base64). |
+| <img src="samples/spa/snippets/file-upload/sharepoint/screenshot.png" alt="SharePoint file upload sample screenshot" width="180" /> | [File Upload (SharePoint) Sample](samples/spa/snippets/file-upload/sharepoint/) | React + Vite | Upload, list, download, and delete files in a SharePoint document library, reached from a code site through server logic and Microsoft Graph. |
+| <img src="samples/spa/snippets/file-upload/azure-blob/screenshot.png" alt="Azure Blob file upload sample screenshot" width="180" /> | [File Upload (Azure Blob) Sample](samples/spa/snippets/file-upload/azure-blob/) | React + Vite | Upload, list, download, and delete files via the Web API, stored in your own Azure Blob container (chunked uploads, up to 10 GB). |
+
+### Traditional sites (`samples/traditional/`)
+
+Non-code sites built with Liquid and web templates on the enhanced data model.
+
+| Sample | Type | Use this sample to learn |
+| --- | --- | --- |
+| [EDM Liquid Web Template Starter](samples/traditional/edm-liquid-webtemplate-starter/) _(planned — placeholder)_ | Liquid + web template | Render Dataverse data on a traditional (non-code) site with a web template and Liquid on the enhanced data model. |
+
+### Server logic (`samples/server-logic/`)
+
+Server-side JavaScript that runs on the Power Pages runtime, callable from both code sites and traditional sites.
+
+| Sample | Integrates | Use this sample to learn |
+| --- | --- | --- |
+| [SharePoint Integration](samples/server-logic/sharepoint-integration/) | Microsoft Graph + SharePoint | Call Microsoft Graph and SharePoint Online from server logic using an Entra client-credentials app. Pairs with the [File Upload (SharePoint)](samples/spa/snippets/file-upload/sharepoint/) code-site sample. |
 
 ## Sample categories
 
-- [SPA Samples](samples/spa/) - code-site samples that use popular frontend frameworks and can be uploaded to Power Pages with the Power Platform CLI.
+- [SPA Samples](samples/spa/) - code-site samples built with popular frontend frameworks and uploaded to Power Pages with the Power Platform CLI. Split into [full applications](samples/spa/apps/) and [single-topic snippets](samples/spa/snippets/).
+- [Traditional Samples](samples/traditional/) - non-code sites built with Liquid and web templates on the enhanced data model.
+- [Server Logic Samples](samples/server-logic/) - server-side JavaScript that runs on the Power Pages runtime.
 
 ## Resources
 

samples/server-logic/README.md

@@ -0,0 +1,13 @@
+# Server logic samples
+
+Server-side JavaScript that runs on the Power Pages runtime and is callable from
+both code sites ([`../spa/`](../spa/)) and traditional sites
+([`../traditional/`](../traditional/)). Server logic keeps secrets off the client
+and lets a site reach services that the portal Web API can't.
+
+| Sample | Integrates | Use this sample to learn |
+| --- | --- | --- |
+| [SharePoint Integration](sharepoint-integration/) | Microsoft Graph + SharePoint | Call Microsoft Graph and SharePoint Online from server logic using an Entra client-credentials app. Pairs with the [File Upload (SharePoint)](../spa/snippets/file-upload/sharepoint/) code-site sample. |
+
+See the repository [CONTRIBUTING guide](../../CONTRIBUTING.md) for how the sample
+categories are organized and where a new sample belongs.

samples/server-logic/sharepoint-integration/readme.md

@@ -2,9 +2,11 @@
 
 This guide walks you through setting up and testing the **Server Logic** sample that integrates Power Pages with **Microsoft Graph** and **SharePoint Online**. 
 
+> **Related sample:** for a full **code site (SPA)** that calls SharePoint through server logic (a file manager UI + companion server-logic file), see [File Upload (SharePoint)](../../spa/snippets/file-upload/sharepoint/).
+
 ## Step 1: Download the sample package 
 
-1. Go to the GitHub repository [https://github.com/microsoft/power-pages-samples/server-logic/sharepoint-integration](https://github.com/microsoft/power-pages-samples/server-logic/sharepoint-integration). 
+1. Go to the GitHub repository [https://github.com/microsoft/power-pages-samples/tree/main/samples/server-logic/sharepoint-integration](https://github.com/microsoft/power-pages-samples/tree/main/samples/server-logic/sharepoint-integration). 
 1. Select **Code \> Download ZIP** (or use git clone if you prefer). 
 
 ```bash