azure-spa-clean-architecture-bootstrap

Files (18)

• SKILL.md
• openai.yaml · agents/
• release-container-image.yml · assets/templates/.github/workflows/
• Dockerfile · assets/templates/
• health.ts · assets/templates/app/routes/
• azure.yaml · assets/templates/
• main.bicep · assets/templates/infra/
• postprovision.sh · assets/templates/scripts/azure/
• azure-identity-and-sql.md · references/
• azure-platform-bootstrap.md · references/
• azure-sql-identity-and-permissions.md · references/
• azure-workload-identity-and-secretless-config.md · references/
• entra-app-registration-cli.md · references/
• entra-user-auth-and-runtime-contracts.md · references/
• github-release-delivery.md · references/
• github-repository-operations.md · references/
• operational-checklist.md · references/
• template-assets.md · references/

SKILL.md (first lines)

# Azure Spa Clean Architecture Bootstrap

## Overview

Use this skill to layer Azure hosting, identity, and GitHub delivery decisions onto the base React Router clean architecture owned by `enforce-react-spa-architecture`. Preserve SPA-style navigation, but switch to a server runtime whenever OAuth callbacks, Prisma, server-only secrets, or Azure SQL access make a static-only SPA the wrong abstraction.
This skill owns Azure platform, `Microsoft Entra ID`, secretless config, IaC, and release workflow guidance. Keep code structure, UI guardrails, and general verification rules in the companion skill, and repeat them here only when they are critical to protect Azure-specific boundaries.
This skill does not own `/doc/spec`, `/doc/plan.md`, commit-log workflow, branch naming workflow, or PR management; use a repository workflow skill for those concerns and keep this skill focused on platform deltas.
Treat requests for "Microsoft auth" as `Microsoft Entra ID` only when the app actually needs user authentication. If the app does not need auth, skip the app registration and auth guidance.
Prefer a secretless configuration model: do not introduce `.env` or `.env.example` for Azure-hosted apps. Put non-secret runtime configuration in Azure App Configuration, put secrets in Key Vault, use local `DefaultAzureCredential` during development, and use `ManagedIdentityCredential` for deployed app-to-Azure and Azure SQL authentication.
Keeping the same database engine across environments is usually safer. When this skill adopts SQLite for developer speed, treat it as local-development-only storage and require Azure SQL Database for every Azure-hosted environment that persists relational data.
Surface Azure prerequisites early. If the project will definitely require specific RBAC assignments, tenant or subscription access, SQL admin setup, App Configuration or Key Vault access, or an unavoidable Service Principal for deploy or migration paths, request those at the beginning of development instead of discovering them mid-implementation.
When the app requires user authentication, prefer a real local sign-in path with a dev or test `Microsoft Entra ID` registration and test identities rather than a hidden development auth bypass.

## Companion Skill Requirement

- Install `enforce-react-spa-architecture` together with this skill. Do not use this skill as a standalone replacement for the base architecture skill.
- If the companion skill is missing, install it before continuing from [https://github.com/anaregdesign/skills/tree/main/skills/development/enforce-react-spa-architecture](https://github.com/anaregdesign/skills/tree/main/skills/development/enforce-react-spa-architecture).
- Prefer `$skill-installer` for the install step when another Codex instance needs to fetch the published skill from GitHub.
- Continue only after the sibling references under `../enforce-react-spa-architecture/references/` are locally available.

## Quick Start

1. Choose the runtime mode first:
   - Keep pure SPA mode only when the app has no server-only secrets, no social login callback, no Prisma-backed mutations, and no protected server endpoints.
   - Use React Router framework runtime when the app needs auth callbacks, cookies, Prisma, Azure SQL, or server-owned secrets.
   - If the app persists relational data, use SQLite for local development and Azure SQL Database for every Azure-hosted environment.
2. Surface prerequisites before deep implementation:
   - list the Azure tenant, subscription, resource group scope, and RBAC assignments that are definitely required
   - identify any required SQL admin or migration identity setup
   - identify whether GitHub Actions OIDC setup or another unavoidable Service Principal is required
   - request these prerequisites at project start instead of waiting for release hardening
3. Confirm the companion skill is installed:
   - required skill: `enforce-react-spa-architecture`
   - published URL: `https://github.com/anaregdesign/skills/tree/main/skills/development/enforce-react-spa-architecture`
   - if missing, install it with `$skill-installer` before reading the sibling references
4. Read the base architecture references from the sibling skill:
   - full architecture overview index for multi-boundary changes: [`../enforce-react-spa-architecture/references/layout-and-dependency-rules.md`](../enforce-react-spa-architecture/references/layout-and-dependency-rules.md)
   - project bootstrap: [`../enforce-react-spa-architecture/references/project-bootstrap.md`](../enforce-react-spa-architecture/references/project-bootstrap.md)
   - layout and module placement: [`../enforce-react-spa-architecture/references/layout-and-module-placement.md`](../enforce-react-spa-architecture/references/layout-and-module-placement.md)
   - client layer responsibilities: [`../enforce-react-spa-architecture/references/client-layer-responsibilities.md`](../enforce-react-spa-architecture/references/client-layer-responsibilities.md)
   - server and domain layer responsibilities: [`../enforce-react-spa-architecture/references/server-and-domain-layer-responsibilities.md`](../enforce-react-spa-architecture/references/server-and-domain-layer-responsibilities.md)
   - boundary and contract rules: [`../enforce-react-spa-architecture/references/boundary-and-contract-rules.md`](../enforce-react-spa-architecture/references/boundary-and-contract-rules.md)
   - domain modeling and type rules: [`../enforce-react-spa-architecture/references/domain-modeling-and-type-rules.md`](../enforce-react-spa-architecture/references/domain-modeling-and-type-rules.md)
   - dependency injection and side-effect rules: [`../enforce-react-spa-architecture/references/dependency-injection-lifetime-and-side-effects.md`](../enforce-react-spa-architecture/references/dependency-injection-lifetime-and-side-effects.md)
   - FlatRoute REST API rules: [`../enforce-react-spa-architecture/references/flat-route-rest-api-guidelines.md`](../enforce-react-spa-architecture/references/flat-route-rest-api-guidelines.md)
   - Prisma boundary rules: [`../enforce-react-spa-architecture/references/prisma-boundary-rules.md`](../enforce-react-spa-architecture/references/prisma-boundary-rules.md)
   - view-state and handler composition: [`../enforce-react-spa-architecture/references/view-state-and-handler-patterns.md`](../enforce-react-spa-architecture/references/view-state-and-handler-patterns.md)
   - chart and data visualization guidance: [`../enforce-react-spa-architecture/references/chart-and-data-visualization-guidance.md`](../enforce-react-spa-architecture/references/chart-and-data-visualization-guidance.md)
   - responsive and mobile UI guidance: [`../enforce-react-spa-architecture/references/responsive-and-mobile-ui-guidance.md`](../enforce-react-spa-architecture/references/responsive-and-mobile-ui-guidance.md)
   - Playwright UI verification workflow: [`../enforce-react-spa-architecture/references/playwright-ui-verification.md`](../enforce-react-spa-architecture/references/playwright-ui-verification.md)
   - stateful flow compromise rules: [`../enforce-react-spa-architecture/references/stateful-flow-compromises.md`](../enforce-react-spa-architecture/references/stateful-flow-compromises.md)
   - hotspot refactor workflow: [`../enforce-react-spa-architecture/references/hotspot-refactor-workflow.md`](../enforce-react-spa-architecture/references/hotspot-refactor-workflow.md)
   - verification gates: [`../enforce-react-spa-architecture/references/verification-gates.md`](../enforce-react-spa-architecture/references/verification-gates.md)
5. Read the Azure and GitHub references in this skill:
   - Azure platform bootstrap: [`references/azure-platform-bootstrap.md`](references/azure-platform-bootstrap.md)
   - Azure identity overview index: [`references/azure-identity-and-sql.md`](references/azure-identity-and-sql.md)
   - user auth, runtime contract, and local sign-in path: [`references/entra-user-auth-and-runtime-contracts.md`](references/entra-user-auth-and-runtime-contracts.md)
   - Azure CLI and `az rest` app registration flow: [`references/entra-app-registration-cli.md`](references/entra-app-registration-cli.md)
   - workload identity and secretless config: [`references/azure-workload-identity-and-secretless-config.md`](references/azure-workload-identity-and-secretless-config.md)
   - Azure SQL identity and permissions: [`references/azure-sql-identity-and-permissions.md`](references/azure-sql-identity-and-permissions.md)
   - GitHub repository operations: [`references/github-repository-operations.md`](references/github-repository-operations.md)
   - GitHub release delivery: [`references/github-release-delivery.md`](references/github-release-delivery.md)
   - template adoption guide: [`references/template-assets.md`](references/template-assets.md)
   - operational checklist: [`references/operational-checklist.md`](references/operational-checklist.md)
6. Classify the change:
   - route or UI composition
   - Microsoft Entra ID auth or app registration when authentication is required
   - auth or session boundary
   - persistence or migration
   - Azure infrastructure
   - GitHub workflow or release automation
   - production verification

## Repository Additions

- Put Azure IaC in `infra/`.
- Put deployment and bootstrap helpers in `scripts/azure/`.
- Put CI and release automation in `.github/workflows/`.
- Keep Azure project wiring in `azure.yaml`.
- Keep container packaging in `Dockerfile`.
- Keep secretless config bootstrap and parsing in `app/lib/server/infrastructure/config/` or the narrowest equivalent server config module.
- Keep configuration contract documentation in `README.md`.
- Add a cheap health probe in `app/routes/health.ts`.

## Template Assets

- Use the generic repo templates in `assets/templates/`.
- Replace placeholder tokens such as `__APP_NAME__`, `__SERVICE_NAME__`, and `__PUBLIC_APP_URL__` only after the target app's naming rules are clear.
- Keep the template vocabulary generic. Do not leak app-specific names, resource-group names, or domain nouns back into the shared asset files.
- Start from these templates when bootstrapping:
  - `assets/templates/azure.yaml`
  - `assets/templates/Dockerfile`
  - `assets/templates/app/routes/health.ts`
  - `assets/templates/.github/workflows/release-container-image.yml`
  - `assets/templates/scripts/azure/postprovision.sh`
  - `assets/templates/infra/main.bicep`

## Non-Negotiable Rules

- Install and keep `enforce-react-spa-architecture` available together with this skill.
- Keep all dependency, placement, UI, and verification rules from `enforce-react-spa-architecture`.
- Do not redefine the companion skill's general coding guardrails here. Use this skill for Azure, identity, infrastructure, and delivery deltas, and repeat code-level rules only when they protect those deltas.
- Keep Prisma and Azure SDK imports inside server infrastructure or deployment code.
- Treat "SPA" as a UX target, not as a requirement to remove the server runtime.
- Prefer React Router framework runtime over bolting ad hoc APIs onto a static bundle when auth, persistence, or secret-backed integrations need a server.
- Prefer Azure Container Apps for apps that need a server runtime. Use Static Web Apps only for truly static frontends.
- Use SQLite only for local development.
- When the app is hosted on Azure and persists relational data, use Azure SQL Database rather than SQLite.
- Prefer Azure SQL Database serverless for Azure-hosted relational persistence unless workload characteristics force another SKU.
- Front-load known Azure prerequisites. Ask for required tenant access, subscription access, RBAC assignments, SQL admin setup, and any unavoidable Service Principal before substantial implementation begins.
- When authentication is required, prefer `Microsoft Entra ID` over portal-only or ad hoc "Microsoft auth" descriptions, and keep the chosen `signInAudience` explicit.
- Do not use `.env` or `.env.example` for Azure runtime configuration. Use Azure App Configuration for non-secret settings and Key Vault for secrets.
- Use local `DefaultAzureCredential` during development after `az login` or `azd auth login`.
- Use `ManagedIdentityCredential` for deployed app-to-Azure and Azure SQL authentication. Do not rely on a broad `DefaultAzureCredential` chain in production.
- Use `DefaultAzureCredential` or Managed Identity only where runtime SDK support is real. Do not assume Prisma CLI or schema migration flows inherit that auth automatically.
- Treat SQLite-to-Azure-SQL provider differences as real delivery risk. Validate migrations, query behavior, and generated SQL against Azure SQL Database before release.
- Separate runtime identity from migration or admin identity.
- When the app requires user authentication, prefer a separate dev or test app registration from the production registration, and use a separate test tenant when production-tenant policies or risk make safe testing hard.
- Keep localhost redirect URIs in the dev or test registration, or document clearly why they still exist in another registration. Remove unnecessary development redirect URIs from the production registration.

From anaregdesign/skills, MIT.

More from anaregdesign/skills