noel-mathews-org/flowforge-terraform

1. This repository is an Azure infrastructure-as-code codebase, not an application runtime repo. Its core purpose is to provision and manage the FlowForge platform using Terraform, with GitHub Actions as the deployment control plane.

2. The Terraform structure is split into two layers:

- modules/ contains reusable building blocks for each Azure subsystem.

- env/ contains environment compositions (dev, og-prod, prod) that wire those modules together with environment-specific variables, provider config, and outputs.

3. The environment split is architecturally important:

- env/og-prod is the bootstrap/persistent foundation, creating long-lived assets such as the Azure Container Registry and user-assigned managed identities.

- env/prod is the destroy/recreate-friendly production stack that treats those identities and registry as external data sources, so the rest of the platform can be torn down and rebuilt without breaking identity continuity or image storage.

- env/dev appears to be the lower-risk equivalent for non-prod testing.

4. The main network model is hub-and-spoke. modules/hub_network hosts the management plane, while modules/spoke_network hosts application-facing subnets. The spoke includes dedicated areas for AKS, Application Gateway, private endpoints, and database connectivity. Private DNS zones are part of this design so services resolve Azure private-link endpoints inside the VNet.

5. Security and traffic control are centralized in a few network boundaries:

- modules/firewall is the forced egress point for AKS and other workloads, enforcing outbound filtering through user-defined routes.

- modules/vpn_gateway provides point-to-site administrative access into the private network using Entra ID authentication.

- modules/app_gateway is the public ingress layer, terminating TLS and forwarding traffic into AKS.

- modules/jumpbox gives operators a private Windows administration host inside the hub network.

6. The core compute boundary is modules/aks. AKS is configured with OIDC issuer and Workload Identity, which is a major architectural choice: application pods authenticate to Azure using federated identities instead of secrets. The cluster appears to use separate system and user node pools, with the user pool carrying the FlowForge workloads.

7. The platform data layer is private-by-default. modules/databases provisions PostgreSQL Flexible Server and Redis, both accessed through private endpoints. modules/storage provides blob storage for application documents or reports, and modules/key_vault stores runtime secrets and connection values. modules/ai_foundry adds an Azure AI/OpenAI-backed service used by the analysis workload.

8. Identity and authorization are a first-class boundary in this repo. The README describes multiple user-assigned managed identities for distinct runtime actors:

- GitHub Actions for pushing images to ACR

- application pods for accessing Key Vault, storage, and database resources

- an ARC runner identity for secret synchronization

- an OpenTelemetry identity for publishing telemetry

- an AI service identity for model invocation

This separation is central to the architecture because it replaces static credentials with short-lived federated access.

9. GitHub Actions is the orchestration layer for infrastructure lifecycle:

- terraform-gitops.yml runs plan/validate/security/cost checks and then waits for environment approval before apply.

- terraform-destroy.yml is a manually dispatched destroy path with an additional text-confirmation safety gate.

- update-keyvault-secrets.yml runs on a self-hosted runner inside AKS to sync GitHub secrets into Key Vault, then disables older secret versions.

The workflows are tied to GitHub Environments, which act as policy and approval boundaries.

10. Remote Terraform state is externalized. scripts/bootstrap_backend.ps1 creates the Azure Storage backend used for .tfstate, and grants the service principal access to that storage account/container. This means state management is part of the platform’s control plane, not stored locally.

11. There is a separate database bootstrap path in db-permission/. It exists because the application uses Entra ID passwordless auth to PostgreSQL, so the database must know about the managed identities. A PowerShell script fetches an AAD token, injects it into a Kubernetes job manifest, and runs a setup job that registers identities and grants database/schema/table privileges.

12. The main data flows are:

- external users enter through Application Gateway into AKS

- AKS workloads reach PostgreSQL, Redis, Storage, and Key Vault over private endpoints

- outbound internet access from AKS is forced through Azure Firewall

- operators enter through VPN Gateway or Jumpbox for private administration

- GitHub Actions drives provisioning, destruction, and secret synchronization through OIDC and federated identities

13. From an architecture-diagram perspective, the important boundaries are:

- GitHub / CI control plane

- Azure subscription and Terraform state backend

- hub network vs spoke application network

- public ingress vs private service access

- persistent bootstrap resources vs destroyable production stack

- identity/auth boundaries between workloads, operators, and pipelines

14. The repository is therefore best understood as an enterprise Azure platform blueprint for a private, identity-driven application stack: Terraform defines the resources, GitHub Actions governs lifecycle, AKS runs the application, and Azure networking/private-link boundaries keep most traffic off the public internet.