Hoppa till innehållet

Arkitekturbeslutsdokument

ett kort dokument om ett arkitekturval och dess skäl

Vad det är

Ett arkitekturbeslutsdokument, ofta kallat ADR, är en kort redogörelse för ett tekniskt val som får betydelse för systemet. Dokumentet säger vad teamet valde, under vilka förutsättningar, vilka realistiska alternativ det fanns och vilka följder valet får. Det kan handla om vem som äger ett slags data, hur tjänster ska sammanfogas eller vad systemet ska göra vid ett visst fel. En ny kollega ska kunna förstå varför lösningen ser ut som den gör och vilka antaganden som fortfarande är relevanta.

Några uppgifter räcker för att göra beslutet användbart. Ett nummer och ett datum gör det lätt att hänvisa till texten. Status visar om beslutet är ett förslag, har antagits eller har ersatts. Bakgrunden beskriver problemet och de konkreta begränsningarna. Beslutet anger vad teamet ska genomföra. Konsekvenserna beskriver både förbättringen och skyldigheterna som följer. En ny tjänst kan behöva skötas av jouren, en övergång ta längre tid eller en migrering behöva övas innan den går att genomföra.

Publicera dokumentet där de berörda redan söker information. Ett team kan lägga korta Markdown-filer vid koden och länka till dem från ändringen som verkställer beslutet. Om flera team delar på arbetet kan de ha ett gemensamt index i stället. En stabil adress och en begriplig motivering gör dokumentet användbart för den som aldrig satt i det ursprungliga mötet. Mätningar, utredningar och tester behöver egna platser, med länkar från beslutet när de påverkar motiveringen.

  • Ett öppet spiralblock och en svart penna på en träyta
    Foto: Engin_Akyurt / Pixabay
  • Närbild på svaga linjer och ett svart band i en öppen anteckningsbok
    Foto: BRRT / Pixabay

Använd begreppet i ett beslut

Använd ”Vad är ett arkitekturbeslutsdokument?” i ett konkret beslut. Vi kan knyta begreppet till systemet ni bygger eller köper. Systemets form utarbetad på papper först, så att delarna passar ihop och kostnaden är känd innan någon skriver kod.

Se våra tjänster Hör av er

Granska antagandena bakom ordet

Använd förklaringen och det länkade arbetet för att formulera frågor till projektet. Vi kan undersöka antagandena tillsammans innan ett verktyg väljs. En infrastrukturplan för 14 avdelningar — 14 forskningsavdelningar under en och samma infrastrukturplan

En infrastrukturplan för 14 avdelningar Hör av er

Varför det spelar roll

Kod visar hur en lösning ser ut idag. Den kan ge ledtrådar om tidigare vägval, men en ny utvecklare ser ibland två databaser och undrar varför de aldrig slogs ihop. Uppdelningen kan ha varit avsedd att isolera en risk medan en leverantör bytte exportformat. Beslutet kan förklara vad teamet ville skydda, varför lösningen passade och vilken händelse som gör det dags att överväga ett alternativ. Det sparar en utredning nästa gång frågan ställs.

Dokumentet ger också utrymme för konkret invändning. Ett förslag kan visa hur ett nytt beroende gör att teamet slipper bygga en egen schemaläggare. Samma beroende kräver att en jourhavande kan återställa schemaläggarens tillstånd. En kollega kan ifrågasätta om behörighet och bemanning finns. Avvägningen blir synlig för dem som senare ska ansvara för driften. När beslutet är fattat kan nästa förvaltare läsa samma förklaring vid överlämningen.

Lägg tid på de val som är dyra att göra om. En ändrad formulering i gränssnittet får oftast en bra förklaring i ändringshistoriken. Ett beslut om vilken tjänst som äger orderregistret, eller hur dubbla betalningar ska undvikas, påverkar flera parter och mer av systemet. Skriv medan alternativen fortfarande är aktuella och ange vilket faktaunderlag teamet hade. Det gör det möjligt att skilja det tidigare beslutet från vad man vet idag.

Så ser det ut i praktiken

I portföljen beskrivs de grundläggande tekniska besluten för en plattform. Beskrivningen gäller val av centrala tekniker medan produktens riktning tog form. Det här är en fiktiv övning som visar hur ett dokument kan fånga ett närliggande vägval om dataägarskap.

En leveranstjänst har ett orderregister och en webbsida där kunden kan se status för sin egen beställning. Vissa leveranshändelser kommer sent. Den offentliga sidan får aldrig visa en annan kunds order. Teamet beslutar att visa status från en separat läsmodell som endast innehåller godkända fält. Att fråga orderregistret direkt skulle kräva färre delar och normalt ge nyare information. Samtidigt skulle den lösningen föra in offentlig trafik och en separat behörighetsgräns vid huvudregistret. Att återanvända nattens export hade varit enkelt, men uppgifter om ändringar under dagen skulle saknas.

Om valet får praktiska följder ska de stå med. Kundtjänst behöver kunna se när den publika vyn har halkat efter och när den interna rutinen gäller. Ett kontraktstest kan fånga ett nytt otillåtet fält. Ge uppdateringsjobbet och larmet en namngiven ägare. Teamet prövar beslutet på nytt om två belastade veckor i följd överskrider gränsen för fördröjning, eller om kravet på avskiljning förändras. En senare läsare kan följa länkarna till provet och till underlaget innan hon föreslår att läsmodellen ersätts.

När ett nytt beslut tar över, skapa en egen post och länka åt båda håll mellan posterna. Bevara det gamla resonemanget för dem som behöver förstå den äldre versionen. En läsare kan hitta vad som gäller genom att titta på titel, datum och status i en kort förteckning.

Den offentliga tjänsten kontrollerar att användaren får se just den beställningen innan den visar status. Testa både att åtkomst till en annan kunds order nekas och exakt vilka fält den tillåtna vyn innehåller.

Var det går fel

Ett dokument som bara gör det valda alternativet trovärdigt tappar sitt värde vid nästa beslut. Ge de andra seriösa alternativen de bästa skäl som faktiskt fanns för dem. Ange källan till ett viktigt påstående, till exempel en mätning, ett villkor eller en standard. Den som senare får annat underlag ska kunna se vilka slutsatser som skulle kunna ändras.

Utelämna heller inte vem som tar hand om följderna. En ny databas eller delad kö kan innebära mer arbete för en annan grupp. Visa vem som ansvarar för drift, underhåll och tillträde. En följd som ännu är oviss kan få en kontrollpunkt med en observerbar signal. Koppla signalen till vad teamet har möjlighet att avgöra vid den tidpunkten.

Håll till sist dokumentet kort nog för att kunna skriva det under pågående arbete. Hänvisa till rutiner som behöver ändras oftare. Vid ett nytt vägval finns då den tidigare motiveringen kvar, samtidigt som läsaren enkelt hittar det beslut som gäller.

Läs mer

Ordlista

Välj utifrån era faktiska förutsättningar

Beskriv arbetsflödet, befintliga gränssnitt och användarna som behöver förändringen. Vi kan definiera en testbar leverans och en överlämning som gör att teamet kan underhålla lösningen.

Se vad det kostar Hör av er

Gör begreppen praktiska

Fråga hur ”Vad är ett arkitekturbeslutsdokument?” gäller i er organisation. Ett konkret exempel från ert nuvarande system räcker för att börja samtalet.

Se våra tjänster
welcome@engineer.company +45 50 10 61 84 Köpenhamn, Danmark
QR-kod för Arkitekturbeslutsdokument
Ta med dig den här sidanhttps://engineer.company/sv/glossary/architecture-decision-record/