Arkitekturbeslutsdokument

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.

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

  * AWS om arbetet med arkitekturbeslutsdokument

  * Microsoft Azure Well-Architected om beslutsdokument

  * Storbritanniens ramverk för arkitekturbeslut

hDen här sidan på webben	URL:https://engineer.company/sv/glossary/architecture-decision-record/	engineer.company	70
