diff --git a/OUTCOMES.md b/OUTCOMES.md new file mode 100644 index 0000000..6add691 --- /dev/null +++ b/OUTCOMES.md @@ -0,0 +1,131 @@ +# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables + +## 1. Executive Summary & Workshop Overview + +The **Cardiff Serverless Days Azure Workshop** provides a comprehensive, hands-on masterclass in constructing, provisioning, automating, and extending modern cloud-native web applications on Microsoft Azure. Centered around a full-stack **Todo application**, the workshop guides participants through the Jamstack architectural paradigm, replacing traditional bespoke CRUD application layers with declarative, database-driven APIs. + +Through this workshop, developers transition from manual resource creation to automated Infrastructure-as-Code (IaC) and Continuous Integration / Continuous Deployment (CI/CD) pipelines, exploring how **Azure Static Web Apps (SWA)**, **Azure SQL Database**, **Data API builder (DAB)**, and **Azure Functions** integrate to deliver scalable, secure, and developer-friendly architectures. + +```mermaid +graph TD + Client["Frontend SPA: Vue.js + Vite"] + Auth["Easy Auth: GitHub IDP"] + SWA["Azure Static Web Apps (SWA) Hosting & Gateway"] + DAB["Data API builder (DAB) / SWA Database Connections"] + AppUser["Runtime Least-Privilege User: todo_dab_user"] + SQL[("Azure SQL Database: TodoDB")] + Functions["Azure Functions: /api/helloworld & BYOF"] + CICD["GitHub Actions: Multi-Branch & PR Previews"] + + Client -->|HTTPS / REST / GraphQL| SWA + SWA -->|GitHub OAuth Authentication| Auth + SWA -->|DAB Engine Proxy| DAB + DAB -->|Connects via todo_dab_user| SQL + SWA -->|Proxies /api/*| Functions + CICD -->|Deploy Production & Staging Previews| SWA + CICD -->|DACPAC Deployment (DDL Admin)| SQL +``` + +--- + +## 2. Architectural Stack & Technology Matrix + +The application leverages Azure serverless and managed cloud components: + +| Layer / Capability | Technology & File References | Role & Responsibility | +| :--- | :--- | :--- | +| **Frontend SPA** | [Vue.js 3 + Vite](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/package.json), [ToDoList.vue](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue) | Responsive Single Page Application handling UI state, drag-and-drop reordering, filtering, and asynchronous HTTP calls. | +| **Hosting & Edge Gateway** | [Azure Static Web Apps (SWA)](https://learn.microsoft.com/azure/static-web-apps/) | Global edge hosting for static assets, unified routing, API reverse proxying, staging preview environments, and authentication routing. | +| **Data Layer** | [Azure SQL Database (`TodoDB`)](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/TodoDB.sqlproj) | Fully managed relational database engine storing entity state across tables defined by [dbo.todos.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql). | +| **API Engine** | [Data API builder (DAB)](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json) | Built-in SWA Database Connections exposing zero-code REST (`/data-api/rest/*`) and GraphQL (`/data-api/graphql`) endpoints with declarative RBAC over Azure SQL. | +| **Identity & Access** | [Static Web Apps Easy Auth](https://learn.microsoft.com/azure/static-web-apps/authentication-authorization) | Turnkey authentication utilizing GitHub as Identity Provider (IDP), passing client identity and roles to the frontend and Data API builder. | +| **Serverless Extensibility** | [Azure Functions (Managed & BYOF)](https://learn.microsoft.com/azure/azure-functions/) | Managed `/api/helloworld` HTTP function and Bring-Your-Own-Functions (`BYOF`) standalone execution for custom computational or integration logic. | +| **CI/CD & Automation** | [GitHub Actions Workflows](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/.github/workflows/) | Automated pipelines managing SQL Server DACPAC schema deployments and SWA production / pull-request preview builds. | + +--- + +## 3. Detailed Learning Outcomes by Module + +### 3.1 Module 1: Serverless Full-Stack Architecture +- **Modern Jamstack Paradigm**: Master the architecture separating client presentation (Vue.js SPA) from persistence (Azure SQL) using cloud-native managed application gateways (Azure Static Web Apps). +- **Zero-Code CRUD Elimination**: Understand how Data API builder (DAB) eliminates the need for maintaining boilerplate controller code, object-relational mappers (ORMs), or traditional CRUD REST APIs. + +### 3.2 Module 2: Cloud Infrastructure & Database Provisioning +- **Azure CLI Automation**: Gain proficiency in provisioning core infrastructure using the Azure CLI (`az cli`): + - Resource group creation (`cardiff-serverless-days`). + - Azure Static Web App creation (`cardiff-serverless-days-webapp`). + - Azure SQL logical server creation (`cardiff-serverless-days-db`) and database initialization (`TodoDB`). +- **Security & Network Configuration**: + - Configuring server-level firewall rules (`AllowAllWindowsAzureIps`) to enable inbound connectivity from Azure services. + - Setting Microsoft Entra ID (Azure Active Directory) administrators via `az sql server ad-admin create` using signed-in user object IDs. +- **Least-Privilege Database Security Pattern**: + - Distinguish between **administrative deployment credentials** (used by CI/CD to apply DDL schema migrations) and **runtime least-privilege database user credentials**. + - Provision and configure the dedicated runtime user `todo_dab_user` (with password `rANd0m_PAzzw0rd!`) in [Script.PostDeployment.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql) and link it securely in Static Web Apps Database Connections. + +### 3.3 Module 3: Automated CI/CD, Multi-Branch & Preview Environments +- **GitHub Secrets Management**: Configure the 6 essential repository secrets required for automated multi-branch deployments: + 1. `AZURE_CLIENT_ID`: Service Principal application client ID for Azure authentication. + 2. `AZURE_CLIENT_SECRET`: Service Principal client secret credential. + 3. `AZURE_TENANT_ID`: Microsoft Entra tenant ID. + 4. `SUBSCRIPTION_ID`: Azure subscription identifier. + 5. `AZURE_STATIC_WEB_APPS_API_TOKEN`: Deployment API token for Azure Static Web Apps. + 6. `AZURE_SQL_CONNECTION_STRING`: ADO.NET connection string targeting `TodoDB` on `cardiff-serverless-days-db` with DDL admin permissions. +- **Service Principal Role-Based Access Control (RBAC)**: Configure a Service Principal (`serverless-days-cardiff-2023-sp`) with `Contributor` role assignment scoped to the resource group or subscription. +- **Multi-Branch CI/CD Triggers**: Implement declarative workflow triggers in GitHub Actions supporting `workflow_dispatch`, branch pushes (`main`, `inprogress`), and pull requests (`[opened, synchronize, reopened, closed]`). +- **Automated Pull-Request Staging Previews**: Leverage Azure SWA staging environments that automatically deploy isolated preview URLs on pull requests, enabling end-to-end acceptance testing prior to merging to `main`. + +### 3.4 Module 4: Database-as-an-API & Declarative Access Control +- **Declarative DAB Configuration**: Configure SWA Database Connections using [staticwebapp.database.config.json](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json) to declare entity models, source SQL tables (`dbo.todos`), and exposed endpoints. +- **Declarative Role-Based Access Control (RBAC)**: + - Configure `anonymous` role access for public operations. + - Configure `authenticated` role access linked to GitHub identity for personalized CRUD actions. + - Implement field-level security and row-level ownership mapping based on user claims. +- **Dual API Surface (REST & GraphQL)**: + - Utilize auto-generated REST endpoints at `/data-api/rest/Todo` supporting standard HTTP verbs (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). + - Explore GraphQL schemas and interactive queries exposed at `/data-api/graphql`. + +### 3.5 Module 5: End-to-End Feature Development & Schema Evolution +- **Database Schema Migration**: + - Extend table definitions in [dbo.todos.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql) to add `[inprogress] [bit] NOT NULL`. + - Establish column default constraints via `ALTER TABLE [dbo].[todos] ADD DEFAULT ((0)) FOR [inprogress]` to allow non-nullable column insertions through DAB without explicit payload omission errors. +- **Seed Data Lifecycle**: Update post-deployment scripts in [Script.PostDeployment.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql) to populate initial `inprogress` boolean values across seed records. +- **Client Application Integration**: + - Update [ToDoList.vue](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue) to incorporate `inprogress` item status toggles, reactive styling classes, and status filtering (`#/inprogress`). + - Invoke auto-generated DAB endpoints with HTTP `PATCH` requests targeting `/data-api/rest/Todo/id/{id}` with partial JSON payloads (`{ inprogress: todo.inprogress, order: todo.order }`). + +### 3.6 Module 6: Serverless API Extensibility & Advanced Tracks +- **Managed Azure Functions**: Implement managed serverless HTTP endpoints such as `/api/helloworld` co-located in the `/api` directory and exposed under the SWA gateway. +- **Client Identity Propagation**: Transmit Easy Auth authentication context (`userDetails` and `clientPrincipal` headers) from the Vue.js frontend into serverless backend functions. +- **Local Developer Experience**: Configure local emulation using `@azure/static-web-apps-cli` (`swa init`, `swa start`) paired with Azure Functions Core Tools (`func`) to simulate frontend, backend, and database connectivity locally. +- **Bring-Your-Own-Functions (BYOF)**: Architectural pattern decoupling Azure Functions into independent standalone Azure Function App resources linked directly into Azure Static Web Apps. + +--- + +## 4. Concrete Deliverables & Verification Checklist + +Participants completing the workshop produce the following verifiable artifacts: + +- [x] **Repository & CI/CD Setup**: + - Forked repository containing client code, database SQL project, DAB configuration, and GitHub Actions workflows. + - 6 configured GitHub Actions Secrets: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, and `AZURE_SQL_CONNECTION_STRING`. + - Service Principal configured with `Contributor` role over the resource group. +- [x] **Cloud Infrastructure**: + - Resource group `cardiff-serverless-days`. + - Azure Static Web App `cardiff-serverless-days-webapp`. + - Azure SQL logical server `cardiff-serverless-days-db` with `AllowAllWindowsAzureIps` firewall rule and Microsoft Entra ID admin. + - Azure SQL Database `TodoDB` deployed via DACPAC action. +- [x] **Secure Runtime Database Connection**: + - Static Web App Database Connection configured using least-privilege user `todo_dab_user` (password `rANd0m_PAzzw0rd!`). + - Declarative configuration via [staticwebapp.database.config.json](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json). +- [x] **Production Application Deployment**: + - Live Vue.js application hosted on Azure Static Web Apps. + - Integrated GitHub Easy Auth for authenticated user sessions. + - Interactive CRUD operations communicating over auto-generated REST (`/data-api/rest/Todo`) and GraphQL (`/data-api/graphql`) endpoints. +- [x] **Feature Branch (`inprogress`) & Preview Environment**: + - Schema extension in [dbo.todos.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql) adding `[inprogress] [bit] NOT NULL` with default constraint `DEFAULT ((0))`. + - Seed data migration updated in [Script.PostDeployment.sql](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql). + - Frontend component updates in [ToDoList.vue](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue) supporting status toggles and filtering. + - Isolated staging/preview environment deployed automatically by Azure SWA on pull request. +- [x] **Serverless API Extensions**: + - Managed `/api/helloworld` Azure Function endpoint integrated into the Vue.js frontend with user identity context propagation. + - Exploration of GraphQL query capabilities and Bring-Your-Own-Functions (`BYOF`) standalone backend architectures. diff --git a/adlc/implement.md b/adlc/implement.md new file mode 100644 index 0000000..0bfe30c --- /dev/null +++ b/adlc/implement.md @@ -0,0 +1,17 @@ +Denied by policy "confirm_run_command". ("denied by pre-tool hook: Denied by policy \"confirm_run_command\".")[`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) has been implemented in the repository root according to [`adlc/specify.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/specify.md) and [`adlc/plan.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/plan.md). + +### Summary of Completed Sections + +1. **Executive Summary & Workshop Overview**: + - Outlines the Jamstack architecture, modern serverless application topology, and zero-code CRUD API layer on Azure. +2. **Architectural Stack & Technology Matrix**: + - Comprehensive matrix covering [Vue.js](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/package.json), Azure Static Web Apps, Azure SQL Database, Data API builder ([`swa-db-connections/staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json)), Easy Auth with GitHub IDP, Azure Functions, and GitHub Actions CI/CD. +3. **Detailed Module Learning Outcomes**: + - **Full-Stack Serverless**: Jamstack paradigm and eliminating boilerplate CRUD code via DAB. + - **Infrastructure & Provisioning**: Azure CLI commands for SWA and Azure SQL, firewall rules (`AllowAllWindowsAzureIps`), Entra ID admin setup, and least-privilege runtime user (`todo_dab_user`). + - **Automated CI/CD & Preview Environments**: 6 GitHub repository secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING`), multi-branch workflows (`main`, `inprogress`), and PR preview staging. + - **Database-as-an-API & Access Control**: [`staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json), role permissions (`anonymous` vs `authenticated`), and REST (`/data-api/rest/*`) / GraphQL (`/data-api/graphql`) endpoints. + - **Schema Evolution & Frontend**: SQL schema evolution in [`dbo.todos.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql) (`[inprogress] [bit] NOT NULL` with `DEFAULT ((0))`), [`Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql) seed script updates, and [`ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue) component integration. + - **Serverless API Extensions**: Managed `/api/helloworld` HTTP endpoint, client authentication propagation, local developer emulation, and Bring-Your-Own-Functions (`BYOF`). +4. **Concrete Deliverables & Verification Checklist**: + - Structured checklist covering configured repository secrets, provisioned cloud resources, live web app with GitHub authentication, DAB endpoints, `inprogress` feature branch with PR previews, and serverless function extensions. diff --git a/adlc/plan.md b/adlc/plan.md new file mode 100644 index 0000000..5d784a9 --- /dev/null +++ b/adlc/plan.md @@ -0,0 +1,151 @@ +# Implementation Plan: Workshop Learning Outcomes & Deliverables Documentation + +## 1. Executive Summary & Objective +This implementation plan defines the complete specification and structural blueprint for generating [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) at the repository root. The document synthesizes the learning outcomes, technical proficiencies gained, architectural patterns, and verifiable deliverables produced throughout the Cardiff Serverless Days Azure Workshop based on [`README.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/README.md) and [`adlc/specify.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/specify.md). + +--- + +## 2. Architectural Overview + +```mermaid +graph TD + Client["Client: Vue.js SPA (Vite)"] + Auth["Easy Auth (GitHub IDP)"] + SWA["Azure Static Web Apps (SWA)"] + DAB["Data API builder (DAB) / SWA Database Connection"] + AppUser["Least-Privilege User: todo_dab_user"] + SQL[("Azure SQL Database: TodoDB")] + Functions["Azure Functions (/api/helloworld & BYOF)"] + CICD["GitHub Actions (Multi-Branch CI/CD)"] + + Client -->|HTTPS / REST / GraphQL| SWA + SWA -->|GitHub OAuth| Auth + SWA -->|DAB Engine| DAB + DAB -->|Connects via todo_dab_user| SQL + SWA -->|Proxies /api| Functions + CICD -->|Deploy Preview / Prod| SWA + CICD -->|DACPAC Deployment DDL Admin| SQL +``` + +--- + +## 3. Resolution of Findings & Key Enhancements + +1. **In-Progress Deliverables Specification**: + - Explicitly detail the database schema evolution in [`database/TodoDB/Tables/dbo.todos.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql) introducing the `[inprogress] BIT NOT NULL` column with the default constraint `ALTER TABLE [dbo].[todos] ADD DEFAULT ((0)) FOR [inprogress]`. + - Explicitly detail post-deployment seed script updates in [`database/TodoDB/Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql) inserting initial values for the `inprogress` column across sample records. + - Explicitly reference frontend updates in [`client/src/components/ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue) including toggle controls, status badge styling, and REST `PATCH` invocations against `/data-api/rest/Todo/id/{id}`. + - Document the lifecycle of Azure SWA isolated pull-request staging preview environments. + +2. **Database Least-Privilege & Application User Architecture**: + - Differentiate between deployment credentials (`AZURE_SQL_CONNECTION_STRING` using SQL Server admin login for DDL operations via SqlAzureDacpacDeployment) and runtime database connection credentials. + - Document the creation and usage of the least-privilege runtime database user `todo_dab_user` (password `rANd0m_PAzzw0rd!`) configured in [`database/TodoDB/Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql) and linked in Azure Static Web Apps Database Connections as specified in [`README.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/README.md) Step 6. + +3. **CI/CD Multi-Branch & PR Workflow Trigger Mechanics**: + - Document GitHub Actions workflow triggers adaptation from [`README.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/README.md) Step 8, supporting `workflow_dispatch`, `push` triggers on `main` and `inprogress`, and `pull_request` triggers (`[opened, synchronize, reopened, closed]`) across branches. + - Explain how pull request events trigger automated provisioning and teardown of preview environments with separate database connection requirements. + +4. **Explicit Target Document Section Outline**: + - Define the exact heading hierarchy and section mapping of [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) to ensure 100% adherence to [`adlc/specify.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/specify.md). + +--- + +## 4. Target Document Structure Outline ([`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md)) + +```markdown +# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables + +## 1. Executive Summary & Workshop Overview +- Purpose of the workshop +- Target audience & core learning objectives +- High-level architectural narrative + +## 2. Architectural Stack & Technology Matrix +- Breakdown table: Layer, Technology, Role / Responsibility + - Frontend: Vue.js SPA + Vite + - Hosting & Platform: Azure Static Web Apps (SWA) + - Data Layer: Azure SQL Database (TodoDB) + - API Engine: Data API builder (DAB) / SWA Database Connections + - Identity & Access: Easy Auth (GitHub IDP) & DAB Role Policies + - Serverless Extensibility: Azure Functions (Managed & BYOF) + - CI/CD & Automation: GitHub Actions (Multi-Branch & PR Previews) + +## 3. Detailed Learning Outcomes by Module +### 3.1 Module 1: Serverless Full-Stack Architecture +- Jamstack principles on Azure +- Eliminating CRUD API boilerplate via Data API builder +### 3.2 Module 2: Cloud Infrastructure & Database Provisioning +- Azure CLI resource group (`cardiff-serverless-days`), SWA, and Azure SQL logical server (`cardiff-serverless-days-db`) provisioning +- Firewall rules (`AllowAllWindowsAzureIps`) and Entra ID (AD) admin configuration +- Least-privilege application user pattern (`todo_dab_user` vs DDL admin credentials) +### 3.3 Module 3: Automated CI/CD, Multi-Branch & Preview Environments +- GitHub Secrets configuration: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING` +- Service Principal RBAC (`Contributor` role assignment) +- Multi-branch and PR workflow triggers (`push`, `pull_request` on `main` and `inprogress`) +- SWA automated preview staging environments for pull requests +### 3.4 Module 4: Database-as-an-API & Declarative Access Control +- SWA Database Connections configuration (`staticwebapp.database.config.json`) +- Entity definitions, permissions mapping (`anonymous` vs `authenticated`), and field-level security +- Auto-generated REST endpoints (`/data-api/rest/*`) and GraphQL endpoints (`/data-api/graphql`) +### 3.5 Module 5: End-to-End Feature Development & Schema Evolution +- SQL schema migration: adding `[inprogress] BIT NOT NULL` with `DEFAULT ((0))` in `dbo.todos.sql` +- Post-deployment seed script updates in `Script.PostDeployment.sql` +- Frontend UI modifications in `ToDoList.vue` (toggle controls, status filtering, REST PATCH integration) +- DAB handling of non-nullable columns with database default constraints +### 3.6 Module 6: Serverless API Extensibility & Advanced Tracks +- Managed Azure Functions HTTP endpoints (`/api/helloworld`) +- Propagating client authentication context (`userDetails`) to serverless APIs +- Local developer emulation tooling (`@azure/static-web-apps-cli`, Azure Functions Core Tools) +- Standalone Bring-Your-Own-Functions (`BYOF`) architecture + +## 4. Concrete Deliverables & Verification Checklist +- Interactive markdown checklist covering: + - Forked & configured repository with 6 CI/CD secrets + - Provisioned Azure cloud resources + - Live deployed Todo web app with GitHub authentication + - Zero-code REST and GraphQL DAB backend over `dbo.todos` + - In-progress feature branch with schema extension (`BIT`, `DEFAULT ((0))`), seed scripts, UI updates, and PR preview deployment + - Managed `/api/helloworld` endpoint & BYOF tracks +``` + +--- + +## 5. Detailed Work Breakdown & Implementation Tasks + +### Task 1: Document Initialization & Header Matching +- Create [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) in the repository root. +- Ensure top-level header is exactly `# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables`. + +### Task 2: Architectural Stack & Technology Matrix Section +- Populate technology table with exact repository references: + - [`client/package.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/package.json) (Vue 3, Vite) + - [`swa-db-connections/staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json) (DAB config) + - [`database/TodoDB/TodoDB.sqlproj`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/TodoDB.sqlproj) (SQL Database Project) + - `.github/workflows/` (GitHub Actions CI/CD) + +### Task 3: Comprehensive Learning Outcomes Breakdown +- Document all 6 modules thoroughly: + - **Module 1 (Full-Stack Serverless)**: Jamstack model, decoupling presentation from persistence, DAB zero-code API generation. + - **Module 2 (Infrastructure & Security)**: Azure CLI provisioning commands, SQL firewall rule configuration, Entra ID admin setup, and least-privilege DAB runtime application user (`todo_dab_user` with password `rANd0m_PAzzw0rd!`). + - **Module 3 (CI/CD & Workflows)**: Explicit documentation of all 6 GitHub secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING`), SP Contributor RBAC, and multi-branch / PR workflow triggers across `main` and `inprogress`. + - **Module 4 (Data API Builder & Security)**: Declarative entity mapping, role authorization (`anonymous` vs `authenticated`), auto-generated REST (`/data-api/rest/Todo`) and GraphQL endpoints (`/data-api/graphql`). + - **Module 5 (Schema Evolution & Frontend)**: Detailed SQL DDL schema changes (`[inprogress] [bit] NOT NULL` with `DEFAULT ((0))`), post-deployment seed scripts (`Script.PostDeployment.sql`), and Vue component integration in [`client/src/components/ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue). + - **Module 6 (API Extensions & Advanced Tracks)**: Managed `/api/helloworld` Azure Function, user identity header propagation (`clientPrincipal`), local emulation with `swa start`, and Bring-Your-Own-Functions (`BYOF`) architecture. + +### Task 4: Concrete Deliverables Checklist +- Detail verification checklist matching [`adlc/specify.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/specify.md) Section 4.3 with full sub-deliverables for the `inprogress` branch, security patterns, and serverless extensions. + +--- + +## 6. Verification & Validation Strategy + +1. **Header Compliance Check**: + - Verify that line 1 of [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) starts with `# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables`. +2. **Secret Coverage Verification**: + - Verify that all 6 secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING`) are present and accurately documented. +3. **In-Progress Feature Verification**: + - Verify presence of `BIT` data type, `DEFAULT ((0))` constraint, [`client/src/components/ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue), [`database/TodoDB/Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql), and isolated PR staging preview environments. +4. **Least-Privilege & Workflow Trigger Verification**: + - Verify documentation of `todo_dab_user` runtime least-privilege user and GitHub Actions `push` / `pull_request` workflow triggers across `main` and `inprogress`. +5. **Formatting & Links**: + - Verify valid markdown links, tables, code blocks, and callouts throughout the generated document. diff --git a/adlc/specify.md b/adlc/specify.md new file mode 100644 index 0000000..65068b8 --- /dev/null +++ b/adlc/specify.md @@ -0,0 +1,73 @@ +# Specification: Workshop Learning Outcomes & Deliverables Documentation + +## 1. Objective +Add a dedicated documentation file, `OUTCOMES.md`, to the repository root that outlines the learning outcomes, technical proficiencies gained, and concrete deliverables produced by completing the Cardiff Serverless Days Azure Workshop. + +--- + +## 2. Background & Motivation +The workshop repository guides attendees through building, deploying, and extending a full-stack serverless Todo application using Azure Static Web Apps (SWA), Azure SQL Database, Data API builder (DAB), and Azure Functions. While [`README.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/README.md) contains step-by-step technical instructions, there is currently no standalone document summarizing the structured learning outcomes, architectural tracks, or concrete deliverable verification checklist for attendees. + +--- + +## 3. Scope & Target File +- **Target File**: `OUTCOMES.md` (root directory) +- **Primary Heading**: `# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables` + +--- + +## 4. Key Requirements & Content Specifications + +### 4.1 Target Audience & Workshop Overview +- Clear statement of workshop goals and architectural stack: + - **Frontend**: [Vue.js](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/package.json) Single Page Application (SPA) with Vite. + - **Hosting & CI/CD**: Azure Static Web Apps (SWA) and GitHub Actions. + - **Data Layer & API Engine**: Azure SQL Database integrated with Azure Static Web Apps Database Connections powered by Data API builder (DAB) exposing REST and GraphQL endpoints. + - **Identity & Security**: Easy Auth configured with GitHub Identity Provider (IDP) and DAB role-based authorization policies (`anonymous` vs `authenticated`). + - **Serverless API Extensibility**: Managed Azure Functions HTTP endpoints and Bring-Your-Own-Functions (BYOF) standalone architectures. + +### 4.2 Learning Outcomes +The document must detail the specific knowledge and skills acquired across the workshop modules: +1. **Serverless Full-Stack Architecture**: + - Understanding Jamstack and modern serverless web architectures on Azure. + - Eliminating boilerplate CRUD API code using Data API builder directly over Azure SQL. +2. **Cloud Infrastructure & Provisioning**: + - Creating resource groups (`cardiff-serverless-days`), Azure Static Web Apps, and Azure SQL logical servers (`cardiff-serverless-days-db`) hosting the `TodoDB` database using Azure CLI (`az cli`). + - Configuring Azure SQL firewall rules, Active Directory (Entra ID) administrators, and Service Principals with RBAC. +3. **Automated CI/CD & Preview Environments**: + - Configuring required GitHub repository secrets: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, and `AZURE_SQL_CONNECTION_STRING`. + - Understanding GitHub Actions workflow automation for production deployments and isolated staging/preview pull-request environments. +4. **Database-as-an-API & Declarative Access Control**: + - Connecting SWA database connections to Azure SQL using DAB configuration ([`swa-db-connections/staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json)). + - Applying granular entity-level permissions, field-level access, and user identity mapping (`authenticated` vs `anonymous`). + - Exploring auto-generated REST endpoints (`/data-api/rest/*`) and GraphQL endpoints (`/data-api/graphql`). +5. **End-to-End Feature Development & Schema Evolution**: + - Implementing schema updates in SQL Server DDL ([`database/TodoDB/Tables/dbo.todos.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql)) and post-deployment scripts ([`database/TodoDB/Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql)). + - Specifying non-nullable column default constraints (`ALTER TABLE [dbo].[todos] ADD DEFAULT ((0)) FOR [inprogress]`) to ensure seamless frontend insertions via DAB without default value omission errors. + - Consuming auto-generated DAB REST endpoints (`PATCH`, `GET`, `POST`, `DELETE`) from Vue.js components. +6. **Serverless API Extension & Advanced Architectural Tracks**: + - Creating and deploying managed Azure Functions HTTP endpoints within Azure Static Web Apps. + - Calling managed APIs with authenticated user context (`userDetails`) from client components. + - Configuring local developer tooling with SWA CLI (`swa`) and Azure Functions Core Tools (`func`). + - Exploring Bring-Your-Own-Functions (`BYOF`) to link standalone Azure Functions backend resources. + +### 4.3 Concrete Deliverables & Milestones +The document must provide a checklist of artifacts and running systems built during the workshop: +- [x] **Forked & Cloned Repository**: Personal Git repository configured with CI/CD workflows and all required secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING`). +- [x] **Provisioned Azure Resources**: Resource group `cardiff-serverless-days`, Azure Static Web App, and Azure SQL Logical Server (`cardiff-serverless-days-db`) hosting the `TodoDB` database. +- [x] **Live Deployed Todo Web App**: Fully functional production Vue.js application deployed to Azure Static Web Apps with Easy Auth GitHub authentication. +- [x] **Integrated Data API Builder Backend**: Zero-code REST and GraphQL APIs exposing CRUD operations over Azure SQL table `dbo.todos`. +- [x] **In-Progress Feature Branch**: Custom feature branch `inprogress` showcasing: + - Database schema extension (`inprogress` `BIT` column with default constraint `DEFAULT ((0))`). + - Updated post-deployment seed scripts (`Script.PostDeployment.sql`). + - Updated Vue.js UI ([`ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue)) with toggle controls and status filtering. + - Working isolated preview environment generated by Azure SWA on pull request. +- [x] **Managed & Standalone Serverless Function Extensions**: Working `/api/helloworld` HTTP endpoint invoked by the client application with user details, alongside GraphQL querying and Bring-Your-Own-Functions (`BYOF`) architecture tracks. + +--- + +## 5. Acceptance Criteria +1. **Document Location & Naming**: File `OUTCOMES.md` exists in the repository root. +2. **Header Matching**: Exact top-level heading must match `# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables`. +3. **Completeness**: Document covers all architectural layers (Frontend, SWA, DAB REST/GraphQL, SQL Server/Database, CI/CD secrets including `SUBSCRIPTION_ID`, Easy Auth, Managed Azure Functions, and BYOF tracks) and aligns directly with [`README.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/README.md). +4. **Formatting & Structure**: Clean GitHub Flavored Markdown with structured headings, checklists, and documentation links. diff --git a/adlc/tasks.md b/adlc/tasks.md new file mode 100644 index 0000000..1fb0a00 --- /dev/null +++ b/adlc/tasks.md @@ -0,0 +1,63 @@ +# Tasks: Workshop Learning Outcomes & Deliverables Documentation + +This task list guides the implementation of [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) in the repository root according to [`adlc/specify.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/specify.md) and [`adlc/plan.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/adlc/plan.md). + +--- + +## Task 1: Create Document Foundation & Architecture Matrix +- [ ] Create [`OUTCOMES.md`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/OUTCOMES.md) in the repository root. +- [ ] Set exact level 1 heading: `# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables`. +- [ ] Author **Section 1: Executive Summary & Workshop Overview** explaining the workshop goals, full-stack Jamstack paradigm, and serverless application topology. +- [ ] Author **Section 2: Architectural Stack & Technology Matrix** featuring a table mapping: + - **Frontend**: [Vue.js](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/package.json) SPA with Vite. + - **Hosting & Platform**: Azure Static Web Apps (SWA). + - **Data Layer**: Azure SQL Database (`TodoDB`). + - **API Engine**: Data API builder (DAB) / SWA Database Connections ([`swa-db-connections/staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json)). + - **Identity & Access**: Easy Auth with GitHub IDP & DAB role-based authorization policies. + - **Serverless API Extensibility**: Managed Azure Functions HTTP endpoints & Bring-Your-Own-Functions (BYOF). + - **CI/CD & Automation**: GitHub Actions multi-branch workflows and pull-request staging previews. + +--- + +## Task 2: Document Detailed Module Learning Outcomes +- [ ] **Section 3.1: Serverless Full-Stack Architecture**: Detail modern Azure Jamstack principles and elimination of CRUD API boilerplate via Data API builder. +- [ ] **Section 3.2: Cloud Infrastructure & Provisioning**: Document resource group (`cardiff-serverless-days`), SWA, and Azure SQL logical server (`cardiff-serverless-days-db`) provisioning via Azure CLI, firewall rules (`AllowAllWindowsAzureIps`), Entra ID admin configuration, and least-privilege runtime database user pattern (`todo_dab_user` with password `rANd0m_PAzzw0rd!`). +- [ ] **Section 3.3: Automated CI/CD, Multi-Branch & Preview Environments**: Detail the 6 required GitHub repository secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `SUBSCRIPTION_ID`, `AZURE_STATIC_WEB_APPS_API_TOKEN`, `AZURE_SQL_CONNECTION_STRING`), Contributor Service Principal RBAC, multi-branch workflow triggers (`push` on `main`/`inprogress`, `pull_request` triggers), and automated PR staging preview environments. +- [ ] **Section 3.4: Database-as-an-API & Declarative Access Control**: Explain [`swa-db-connections/staticwebapp.database.config.json`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/swa-db-connections/staticwebapp.database.config.json), entity mapping, RBAC permissions (`anonymous` vs `authenticated`), field-level security, and auto-generated REST (`/data-api/rest/*`) and GraphQL (`/data-api/graphql`) endpoints. +- [ ] **Section 3.5: End-to-End Feature Development & Schema Evolution**: Detail database schema changes in [`database/TodoDB/Tables/dbo.todos.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Tables/dbo.todos.sql) introducing `[inprogress] BIT NOT NULL` with `DEFAULT ((0))`, post-deployment seed scripts in [`database/TodoDB/Script.PostDeployment.sql`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/database/TodoDB/Script.PostDeployment.sql), and frontend component updates in [`client/src/components/ToDoList.vue`](file:///home/admin_owaino_altostrat_com/.ai-sdlc/projects/cardiff-serverless-days-workshop/.worktrees/run-2026082514030770/client/src/components/ToDoList.vue). +- [ ] **Section 3.6: Serverless API Extensibility & Advanced Tracks**: Detail managed `/api/helloworld` Azure Function endpoint, client authentication context propagation (`userDetails` / `clientPrincipal`), local developer emulation with SWA CLI / Functions Core Tools, and Bring-Your-Own-Functions (`BYOF`) standalone architecture. + +--- + +## Task 3: Author Concrete Deliverables & Verification Checklist +- [ ] **Section 4: Concrete Deliverables & Verification Checklist**: Implement a structured markdown checklist covering: + - Configured repository with all 6 CI/CD secrets. + - Provisioned Azure cloud resources. + - Live deployed Vue.js web app with GitHub authentication. + - Zero-code REST and GraphQL DAB backend over `dbo.todos`. + - In-progress feature branch with SQL schema migration (`BIT`, `DEFAULT ((0))`), post-deployment scripts, UI updates, and PR preview deployment. + - Managed `/api/helloworld` endpoint & BYOF architecture tracks. + +--- + +## Task 4: Markdown Formatting & Verification +- [ ] Ensure formatting uses GitHub Flavored Markdown with clean headers, callouts, bullet points, and code spans. +- [ ] Verify that all required keywords and section references pass the verify commands. + +```verify +test -f OUTCOMES.md +grep -Fq "# Cardiff Serverless Days Workshop: Learning Outcomes & Deliverables" OUTCOMES.md +grep -Fq "AZURE_CLIENT_ID" OUTCOMES.md +grep -Fq "AZURE_CLIENT_SECRET" OUTCOMES.md +grep -Fq "AZURE_TENANT_ID" OUTCOMES.md +grep -Fq "SUBSCRIPTION_ID" OUTCOMES.md +grep -Fq "AZURE_STATIC_WEB_APPS_API_TOKEN" OUTCOMES.md +grep -Fq "AZURE_SQL_CONNECTION_STRING" OUTCOMES.md +grep -Fq "todo_dab_user" OUTCOMES.md +grep -Fq "DEFAULT ((0))" OUTCOMES.md +grep -Fq "/api/helloworld" OUTCOMES.md +grep -Fq "staticwebapp.database.config.json" OUTCOMES.md +grep -Fq "ToDoList.vue" OUTCOMES.md +grep -Fq "Script.PostDeployment.sql" OUTCOMES.md +grep -Fq "dbo.todos.sql" OUTCOMES.md +```