logo
Forge
Overview
Initializing search
    • Forge
    • Learn
    • Build
    • Troubleshoot
    • Reference
    • Release Notes
    • About
    • Forge
    • Learn
      • SAIF CLI Installation
      • Set up Forge Agent Plugins
      • Create projects with Forge templates
      • Tutorials
        • Build on Your App
      • Migration
        • Forge v2 to v3
        • Test Tools Migration (Forge v2 to v3)
        • Agent-Assisted Migration to Forge v3
        • Migrate to saif-business-roles
    • Build
      • Identity
          • App Permissions
          • Aspire Security Configuration
          • Business Roles
          • Identity Deployment Workflow
          • Entra Security Groups for Access Grants
          • Subscription Key Authentication
          • User Permissions
          • JWT Test Tokens
          • Test Tools Repository
          • External Test Users
          • Non-Production Roles
      • Data
        • Cosmos DB NoSQL
        • Oracle Database
        • Blob Storage
      • Eventing
        • Event Service
        • Event Subscriptions
        • Service Bus Queue
      • APIs
        • TypeSpec API Design
        • Downstream API Calls
        • Webhooks
          • Filevine Webhook Integration
      • Configuration
        • Feature Flags
        • Settings and Secrets
      • Local development
        • Mocking
          • WireMock Hosting
          • WireMock Runner Hosting
          • WireMock Recording
      • Deployment
        • Aspire Publish
        • Blue-Green Deployments
        • Custom Subdomains
        • Documentation Site
        • PR Slot Deployments
      • Observability
      • Testing
        • API Testing with Aspire
        • Integration Test Environment Variables
        • Web Testing with Playwright
      • Examples
          • Blob Storage Integration
          • Aspire Configuration Example
          • Playwright Integration Testing
          • WireMock CLI Example
          • WireMock Runner Example
          • DevTunnels Webhook Example
          • Event Orchestration Example
          • Events with Cosmos DB Example
          • APIM Policy Example
    • Troubleshoot
      • Catalog
      • Terraform apply fails: Provider produced inconsistent final plan (application_permissions)
      • Terraform apply fails: resource already exists - to be imported into the State (application_permissions)
      • Aspire AppHost SDK not found (MSB4236)
      • Blob storage calls fail with 403 AuthorizationPermissionMismatch, app unhealthy
      • Event service PR pipeline fails with template not found
      • Terraform apply still fails with 409 RoleAssignmentExists after upgrading past 3.8.6
      • Function App deploy warns "Invalid version" for runtime and then times out
      • Function App deploy fails: service_plan_id is required
      • Kiota-generated client fails with CS0103 for Status
      • Terraform apply fails with 'no OAuth application found with the provided label' even though the Okta app exists
      • saif publish does not create Azure DevOps pipelines for a new or renamed repo
      • saif publish fails: Remote 'origin' already exists with different URL
      • Terraform plan fails: network_rules_default_action is null
      • Terraform provider authentication fails because workspace variable sets are missing
      • VSTest target is no longer supported on .NET 10
    • Reference
      • Authorization
      • CLI Workflows
      • Write answer-first troubleshooting documentation
      • Documentation Retrieval
      • Environments
      • Read pipeline logs
      • Pipelines
      • @saif/platform-typespec
      • Service ↔ Azure Resource Model
      • Smithy
      • Browse by tag
      • Version Compatibility Matrix
      • Architecture
        • Golden Path
        • How Authentication Works
      • Decisions
        • Use Markdown Architectural Decision Records
        • Terraform State and Module Management
        • All API Endpoints Require Authentication
        • All Non-Api Management Azure Resources Will Have Private Endpoints
        • Preferred Method of Deployment of APIs
        • Subdomain Names of Applications and APIs
        • Okta Multi-Tenant Architecture
        • Observability and Monitoring
        • Terraform Linting
        • On-Premise Authentication to Forge Applications
        • Feature Flag Provider Selection
        • Shared Platform SDK and Tiered Documentation Search
        • Migrate Forge Skills into Two Agent Plugins Packages
        • Author Forge Skills in .github/skills and Generate Plugin Copies
        • Adopt MCP 2026-07-28 and Explicit Conversation IDs
      • Diagnostics
        • SAIFENV001: SAIF Environment API is Experimental
        • SAIFMOCK001: WireMock Runner API is Experimental
        • SAIFPIPELINES001: Pipeline Generation API is Experimental
        • SAIFSECURITY001: Security Configuration API is Experimental
      • Dotnet
        • SAIF.Platform
        • SAIF.Platform.Aspire.Hosting
        • SAIF.Platform.AspNetCore
        • SAIF.Platform.Authentication
        • SAIF.Platform.Authentication.AspNetCore
        • SAIF.Platform.Azure
        • SAIF.Platform.EntityFramework
        • SAIF.Platform.Kiota.HttpClientLibrary
        • SAIF.Platform.Templates
        • SAIF.Platform.CLI
          • SAIF CLI command reference
      • Terraform
        • saif-api-service
        • saif-application-permissions
        • saif-business-roles-corp
        • saif-business-roles-external
        • saif-event-subscriber-service
        • saif-openapi
        • tfe-bootstrap-ext-test-users
        • tfe-bootstrapper
        • tfe-bootstrapper-business-roles
        • tfe-project-permissions
        • saif-event-service
          • saif-event-service / bootstrapper
          • saif-event-service / operation_naming
          • saif-event-service / servicebus_policy
        • saif-resources
          • saif-resources / ai-project
          • saif-resources / api
          • saif-resources / bot
          • saif-resources / cosmosdb
          • saif-resources / custom-subdomain
          • saif-resources / environment
          • saif-resources / external-identity
          • saif-resources / identity
          • saif-resources / servicebus-queue
          • saif-resources / storage
          • saif-resources / webapp
          • saif-resources / webapp-route
        • saif-staticsite-service
          • saif-staticsite-service / bootstrapper
        • saif-utilities
          • saif-utilities / namer
          • saif-utilities / naming
          • saif-utilities / naming / tests
          • saif-utilities / openapi_parser
          • saif-utilities / openapi_parser / security
          • saif-utilities / string_utilities
          • saif-utilities / string_utilities / casing
            • saif-utilities / examples / naming-database
            • saif-utilities / examples / openapi-parser
        • saif-web-service
          • saif-web-service / bootstrapper
      • Typescript
        • @saif/platform
        • @saif/platform-react
        • @saif/platform-typespec
    • Release Notes
      • 3.9.3
      • 3.9.2
      • 3.9.1
      • 3.9.0
      • 3.8.6
      • 3.8.5
      • 3.8.4
      • 3.8.3
      • 3.8.2
      • 3.8.1
      • 3.8.0
      • 3.7.5
      • 3.7.4
      • 3.7.3
      • 3.7.2
      • 3.7.1
      • 3.7.0
      • 3.6.7
      • 3.6.6
      • 3.6.5
      • 3.6.4
      • 3.6.3
      • 3.6.2
      • 3.6.1
      • 3.6.0
      • 3.5.2
      • 3.5.0
      • 3.4.0
      • 3.3.0
      • 3.2.7
      • 3.2.6
      • 3.2.5
      • 3.2.4
      • 3.2.3
      • 3.2.2
      • 3.2.1
      • 3.2.0
      • 3.1.3
      • 3.1.2
      • 3.1.1
      • 3.1.0
      • 3.0.14
      • 3.0.13
      • 3.0.12
      • 3.0.11
      • 3.0.10
      • 3.0.9
      • 3.0.8
      • 3.0.7
      • 3.0.6
      • 3.0.5
      • 3.0.4
      • 3.0.3
      • 3.0.2
      • 3.0.1
      • 3.0.0
      • 2.1.25
      • 2.1.24
      • 2.1.23
      • 2.1.22
      • 2.1.21
      • 2.1.20
      • 2.1.19
      • 2.1.18
      • 2.1.17
      • 2.1.16
    • About
      • Platform Overview
      • History
      • Principles
      • Technology Vision

    Architectural Decision Records¶

    Architectural Decision Records (ADRs) capture significant technical and architectural choices made for this platform. Use this section to browse past decisions, understand their context, and ensure new work aligns with established direction.

    • 0000-use-markdown-architectural-decision-records
    • 0001-terraform-state-and-module-management
    • 0002-all-api-endpoints-require-authentication
    • 0003-all-non-api-management-azure-resources-will-have-private-endpoints
    • 0004-preferred-method-of-deployment-of-apis
    • 0005-subdomain-names-of-applications-and-apis
    • 0006-okta-multi-tenant-architecture
    • 0007-observability-and-monitoring
    • 0008-terraform-linting
    • 0009-on-premise-authentication-to-forge
    • 0010-feature-flag-provider-selection
    • 0011-shared-platform-sdk-and-tiered-documentation-search
    • 0012-migrate-forge-skills-into-two-agent-plugins-packages
    • 0013-author-forge-skills-in-github-skills-and-generate-plugin-copies
    • 0014-adopt-mcp-2026-07-28-and-explicit-conversation-ids
    August 10, 2026
    Made with Material for MkDocs