Besluiten¶
De codebase van de portal legt zijn ontwerpbesluiten vast als Architecture Decision Records (ADR's). Deze pagina vat ze samen. De status is die uit de bron: accepted betekent dat het besluit van kracht is, proposed dat het is opgeschreven maar niet bevestigd, superseded dat een later record het heeft vervangen. Namen van besluitvormers zijn weggelaten.
Overzicht¶
| Nr. | Besluit | Status |
|---|---|---|
| 0001 | Azure Functions-backend voor cost insights | Superseded door 0002 |
| 0002 | ASP.NET Core voor backends | Superseded door 0015 |
| 0003 | Backstage in de root van de repository | Accepted |
| 0004 | Standaardwijzigingen in landing zones automatiseren | Superseded door 0015 |
| 0005 | Projectstructuur afgestemd op ports and adapters | Accepted |
| 0006 | Managed service-aanbod als custom entities in de software catalog | Accepted |
| 0007 | Eén gedeelde codebase voor alle aanbod | Accepted |
| 0008 | Eén keer bouwen, vaak deployen | Accepted, geïmplementeerd met GitHub Actions |
| 0009 | Aparte main.tf per klant per omgeving |
Accepted |
| 0010 | Verbinden met klantomgevingen via private endpoints | Accepted |
| 0011 | Azure Data Factory voor ingestie van kostendata | Accepted |
| 0012 | FOCUS-schema met Parquet en Snappy voor kostenexports | Accepted |
| 0013 | Alle data verwerken in de klantomgeving | Accepted |
| 0014 | Op het thema gebaseerd kleurenschema voor kostengroepen | Accepted |
| 0015 | De backend verenigen op TypeScript | Accepted |
| 0016 | Relationship-based access control voor gevoelige data | Proposed |
| 0017 | Prose linting met Vale | Accepted |
| 0018 | Kostenexports configureren vanuit een achtergrondjob van de portal | Accepted |
| 0019 | Hiërarchie-resolutie via REST in plaats van GraphQL | Accepted |
| 0020 | Eigen skill loading voor de commanding agent | Accepted |
| 0021 | Evaluatiestrategie voor AI-agents | Proposed |
| 0022 | Evaluatie van AI-agents tijdens de ontwikkeling | Proposed |
| 0023 | Live-evaluatie, tracing en feedback voor AI-agents | Proposed |
| 0024 | CI/CD verplaatsen van Azure Pipelines naar GitHub Actions | Accepted |
| 0025 | Geen GitHub Environment op de plan- en build-workflows | Accepted |
| 0026 | De Terraform client secret is een repository secret, opgelost op plantijd | Accepted |
| 0027 | Plan en apply delen één Azure-identity | Accepted |
| 0028 | De build-workflow bevat geen Azure-credential | Accepted |
| 0029 | Configuratie per omgeving staat in het omgevingenbestand | Accepted |
| 0030 | AI-agents draaien als in-process loop in plaats van Foundry Agent Service | Accepted |
Product en codebase¶
Eén codebase (0007, 0003, 0005). Alle klanten draaien dezelfde code. Er worden geen klantspecifieke codewijzigingen gedaan; een verzoek dat niet past, wordt via de solution lead apart featurewerk. De code is georganiseerd volgens ports and adapters, met de Backstage-app in de root van de repository.
Custom entity kinds (0006). De catalog modelleert aanbod, klanten en workloads met custom kinds in plaats van het standaard systeemmodel te verbuigen. Zie Catalog en entity model.
TypeScript-backend (0015). De eerdere C#-backends en de Azure Functions-aanpak (0001, 0002) en de PowerShell-gebaseerde automatisering van standaardwijzigingen (0004) zijn vervangen door één TypeScript-backend in de portal.
REST boven GraphQL (0019). De hiërarchie van organisatie, domein, team, workload en subscription wordt opgelost door een gedeelde service achter REST-routes en MCP-acties. Het besluit geeft de voorkeur aan REST omdat dat aansluit op Backstage en AI-gegenereerde requests een eenvoudiger oppervlak geeft.
Data en security¶
Private endpoints (0010). De provider deelt zijn broncode niet, draait geen agent pool in het netwerk van de klant en bewaart geen klantdata zoals Terraform state. Daarom verbindt hij via private endpoints die hij in zijn eigen netwerk aanmaakt en die de klant goedkeurt. De klant kan de verbinding intrekken. Zie Een klant onboarden.
Data blijft in de klantomgeving (0013). Kostendata wordt geëxporteerd en verwerkt in de subscription van de klant, waardoor de provider buiten de rol van verwerker blijft. Hetzelfde principe lag ten grondslag aan de in-process agent loop (0030).
Toegangsbeheer (0016). Het voorstel breidt het Backstage-permissiesysteem uit met een eigenaarscontrole, in plaats van een aparte autorisatieservice of een relationship-based store toe te voegen. Overzichtsscores blijven zichtbaar voor elke aangemelde gebruiker; details zijn zichtbaar voor eigenaren; toegangscontroles worden geaudit. De code implementeert de permissies voor firewalllogs, geblokkeerde gatewayrequests, securitydetail en compliancedetail, ook al staat het record nog op proposed. Het voorstel noemt kostendata ook als gevoelig, maar de code beperkt de toegang daartoe niet. Zie Authenticatie en toegang.
Cost insights¶
Data Factory, FOCUS, Parquet (0011, 0012). Exports van Cost Management gaan in FOCUS-formaat met Parquet en Snappy naar storage en Data Factory laadt ze in SQL.
Exports geconfigureerd door de portal (0018). Een achtergrondjob in de portal maakt de exports aan, dus een aparte pipeline is niet nodig. Zie Cost insights setup.
Delivery¶
Eén keer bouwen, vaak deployen (0008, 0028). Per run wordt één image gebouwd. De buildjob heeft geen Azure-credential.
Aparte roots (0009). Eén Terraform root per klant en omgeving, zodat een wijziging voor de ene geen andere kan raken.
GitHub Actions met OIDC (0024). De pipelines zijn verhuisd naar GitHub Actions. Plan en build draaien zonder GitHub Environment (0025), zodat het leesbare plan bestaat vóór de goedkeuring. De Terraform client secret is een repository secret omdat het plan ongewijzigd wordt toegepast (0026). Eén JSON-bestand bevat de configuratie per omgeving (0029).
Openstaand risico (0027). Plan en apply gebruiken dezelfde Azure-identity omdat de read-only identity voor plan nog niet bestaat. Het besluit houdt de splitsing omkeerbaar. Zie Deployment en omgevingen.
AI-agents¶
In-process agent loop (0030). De agents draaiden eerst in de Foundry Agent Service. De standaardopzet richt per klant een database, een searchservice en storage in, wat duur is en hier ongebruikt blijft. De basisopzet verplaatst gesprekken naar een door Microsoft gehoste backend buiten de klantomgeving. Het geaccepteerde besluit draait de loop in de portalbackend en gebruikt Foundry alleen als modelendpoint. Gesprekken worden opgeslagen in de portaldatabase. Zie AI-agents.
Skill loading (0020). De commanding agent delegeert aan de spoke agent en de integration agent door skills te laden, omdat het eerdere connected-agent-model niet beschikbaar is in de nieuwe Foundry agent service.
Evaluatie (0021, 0022, 0023). De voorstellen beschrijven een splitsing tussen evaluatie tijdens de ontwikkeling (Promptfoo) en live-evaluatie. Alle drie zijn nog proposed en geschreven voor de Foundry agent service. Zie Agent-evaluatie.
Records en code die niet overeenkomen
De records 0021 tot en met 0023 en de oudere deploymentgidsen beschrijven nog steeds de Foundry agent service. Het oudere architectuurmodel van de repository toont nog GraphQL en een aparte dataplatformdatabase, terwijl 0015 en 0019 TypeScript en REST beschrijven. Eén record verwijst naar een bestandsnaam die niet bestaat. Als een record en de code niet overeenkomen, winnen de code en de geaccepteerde records.