Nav Architecture Review

Architecture Review — ADR Generator

Generate an Architecture Decision Record (ADR) with review from five perspectives: architecture, security, platform, migration, and user experience. Follow Nav's Architecture Advice Process.

Workflow

1. Forstå konteksten — hva er endringen og hvorfor?
2. Review the five perspectives — architecture, security, platform, migration, and user experience; state when a perspective does not apply.
3. Identifiser alternativer — minst to alternativer + valgt løsning
4. Generer ADR — formelt dokument med Nav-spesifikke vurderinger
5. Liste aksjonspunkter — hva må gjøres for å realisere beslutningen

Steg 1: Kontekst

Still disse spørsmålene:

• Hva er endringen? (én setning)
• Hvorfor gjøres den? (forretningsbehov, teknisk gjeld, regulatorisk)
• Hva er konsekvensen av å ikke gjøre noe?
• Hvilke team påvirkes?

Steg 2: Fler-perspektiv-review

For each perspective, identify concerns, risks, and recommendations, or briefly explain why it does not apply to the change.

Perspektiv 1: Arkitektur

• Passer dette i Navs overordnede arkitektur?
• Finnes det enklere alternativer?
• Introduserer det unødvendig kompleksitet?
• Er det i tråd med team-autonomi-prinsippet?
• Gjenbruker det eksisterende plattform-kapabiliteter?
• Navs prinsipper: Team First, essential complexity, Product Development

Perspektiv 2: Sikkerhet

Dypere sikkerhetsgjennomgang: For trusselmodellering, OWASP-sjekklister og compliance-vurderinger, delegér til @security-champion-agent som har komplett sikkerhetsmateriale.

• Hvilke data behandles? Klassifiseringsnivå?
• Er autentisering og autorisasjon riktig?
• Er tilgangsstyring minimalt nødvendig (least privilege)?
• Er PII beskyttet (logging, lagring, transit)?
• Følger dette Navs Golden Path for sikkerhet?

Perspektiv 3: Plattform

• Fungerer dette på Nais (Kubernetes/GCP)?
• Er ressurskrav realistiske?
• Er observerbarhet ivaretatt?
• Er CI/CD-pipeline enkel og vedlikeholdbar?
• Er det avhengigheter til on-prem eller legacy?

Perspektiv 4: Migrasjon (kun ved endring av eksisterende system)

• Er endringen bakoverkompatibel? Kan gammel kode kjøre med nytt skjema?
• Finnes det en rollback-plan som ikke medfører datatap?
• Er det definert exit criteria for når migreringen er ferdig?
• Er feature toggle satt opp for gradvis utrulling?
• Er berørte konsumenter (andre team/tjenester) identifisert og informert?
• Er det satt opp rekonsiliering for å verifisere datakonsistens?
• Er dekommisjoneringsplan for gammel løsning definert?
• Er migrasjons-observerbarhet på plass (gammel vs ny path, avviksteller)?

Perspective 5: User experience

• Who is affected, and what task must they be able to enter, complete, and check?
• How does each alternative affect that workflow, including navigation, necessary information, feedback, recovery, and accessibility?
• For a plan, inspect the proposed flow and assumptions. For implemented UI, exercise the task on the rendered interface; record what was inspected and any missing evidence.
• Judge reading, comparison, and monitoring views by those jobs. Correct components and passing tests alone do not establish usability.

Steg 3: Alternativer

Identifiser minst to alternativer:

Steg 4: Generer ADR

Bruk malen fra adr-template.md.

markdownCopy code
# ADR-{nummer}: {tittel}

**Dato:** {dato}
**Status:** Foreslått | Godkjent | Forkastet | Erstattet av ADR-{n}
**Beslutningstakere:** {team/personer}

## Kontekst

{Hva er problemet/muligheten? Hvorfor må vi ta en beslutning nå?}

## Beslutning

{Hva har vi besluttet å gjøre?}

## Alternativer vurdert

### Alternativ A: {navn} (valgt)
- **Fordeler:** ...
- **Ulemper:** ...
- **Nav-vurdering:** ...

### Alternativ B: {navn}
- **Fordeler:** ...
- **Ulemper:** ...
- **Nav-vurdering:** ...

## Nav-spesifikke vurderinger

### Sikkerhet
- Dataklassifisering: {nivå}
- Auth-mekanisme: {valgt mekanisme}
- PII-håndtering: {strategi}

### Plattform
- Nais-konfigurasjon: {endringer}
- Ressursbehov: {estimat}
- Observerbarhet: {strategi}

### Team-påvirkning
- Berørte team: {liste}
- Migrasjonsstrategi: {plan}
- Tilbakerulle-strategi: {plan}

### Brukeropplevelse
- Berørte brukere og oppgave: {arbeidsflyt, eller hvorfor det ikke gjelder}
- Effekt av beslutningen: {informasjon, samhandling, universell utforming og feilretting}
- Grunnlag og hull: {foreslått flyt eller utprøvd grensesnitt, åpne antakelser}

### Migrasjon (ved endring av eksisterende system)
- Bakoverkompatibilitet: {vurdering}
- Utrullingsstrategi: {big bang / gradvis / parallell}
- Feature toggle: {toggle-navn og strategi}
- Rollback-trigger: {hva utløser rollback}
- Exit criteria: {når er migreringen ferdig}
- Dekommisjonering: {plan for gammel løsning}

## Konsekvenser

### Positive
- ...

### Negative
- ...

### Risiko
- ...

## Aksjonspunkter

- [ ] {konkret oppgave med eier}

Steg 5: Aksjonspunkter

Avslutt alltid med konkrete aksjonspunkter:

• Implementer beslutningen
• Oppdater Nais-manifest
• Oppdater CI/CD-pipeline
• Informer berørte team
• Oppdater dokumentasjon
• Sett opp observerbarhet

Navs arkitekturprinsipper

Se nav-principles.md for detaljerte prinsipper.

Kort oppsummert:

1. Team First — Autonome team med sirkel av autonomi
2. Essensiell kompleksitet — Unngå accidental complexity
3. Produktutvikling — Kontinuerlig utvikling, produktorganisert gjenbruk
4. DORA-metrikker — Mål og forbedre team-ytelse
5. Architecture Advice Process — Søk råd fra berørte parter, men ta beslutningen selv

Teknisk gjeld-vurdering

Bruk denne strukturen til å identifisere, dokumentere og prioritere teknisk gjeld. Spesielt nyttig ved modernisering og refaktorering.

Identifisering

Still disse spørsmålene for å finne teknisk gjeld:

Prioriteringsmodell

Prioriter gjeldsposter med tre dimensjoner:

Copy code
Prioritet = Alvorlighetsgrad × Frekvens × Nedslagsfelt

Alvorlighetsgrad (1-3):
  1 = Irriterende men håndterbart
  2 = Bremser utvikling merkbart
  3 = Blokkerer ny funksjonalitet eller utgjør sikkerhetsrisiko

Frekvens (1-3):
  1 = Sjeldent (årlig)
  2 = Regelmessig (månedlig)
  3 = Ofte (ukentlig eller daglig)

Nedslagsfelt (1-3):
  1 = Én komponent
  2 = Flere komponenter i samme tjeneste
  3 = På tvers av tjenester/team

Output: Gjeldstabell

markdownCopy code
| # | Gjeldspost | Alv. | Frekv. | Nedslagsfelt | Prioritet | Anbefalt tiltak |
|---|-----------|------|--------|-------------|-----------|----------------|
| G1 | Utdatert auth-bibliotek | 3 | 3 | 2 | 18 | Oppgrader til nyeste navikt/oasis |
| G2 | Manglende testdekning i beregningsmodul | 2 | 3 | 1 | 6 | Skriv karakteriseringstester |
| G3 | Duplisert valideringslogikk | 1 | 2 | 2 | 4 | Ekstraher til felles modul |

Leverabel: Gjeldstabell med prioritert rekkefølge og anbefalt tiltak per post.

Boundaries

✅ Always

• Inkluder minst to alternativer (inkludert «gjøre ingenting»)
• Review all five perspectives; explain any that do not apply.
• Dokumenter Nav-spesifikke vurderinger (auth, data, plattform)
• Avslutt med konkrete aksjonspunkter

⚠️ Ask First

• ADR som påvirker andre teams tjenester
• Beslutninger som avviker fra Navs standardmønstre
• Introduksjon av ny teknologi

🚫 Never

• Fatt beslutning uten å vurdere sikkerhet
• Ignorer plattform-konsekvenser
• Hopp over alternativer — det finnes alltid minst to valg

Review contract

Axes: the five perspectives in Steg 2 — architecture, security, platform, migration, and user experience. State why any axis does not apply. The verdict is on the chosen alternative, and it gates the ADR Status field: BLOCK means the ADR is not approvable as written.

The review ends here, in this shape. A review with no output section has not run.

Judge primary evidence. The diff, the file, the EXPLAIN output, the rendered page — never your own summary of the change, and never your memory of what you meant to write. Resolve the base first, then cover committed, staged, unstaged and untracked changes. Read untracked files in full: diff output omits them.

Every axis reports. Each applicable axis produces at least one finding, or one line saying what it inspected and what that evidence does not prove. For an inapplicable axis, state why. An axis that says nothing has not looked.

Report what you inspected. "No findings in the two files I opened" and "no findings in the change" are different claims, and only the first one is ever true.

Copy code
Inspected:     <files, queries, URLs, viewports actually opened>
Not inspected: <in scope, not examined, and why>
Findings:      <n blocking, n concerns>
Verdict:       BLOCK | CONCERNS | CLEAN

• BLOCK — at least one finding that, shipped as written, risks data loss, a security or privacy breach, a production incident, a wrong answer to a user, or prevents an intended user from completing a critical task.
• CONCERNS — no blocking finding, but at least one a maintainer should fix or answer first.
• CLEAN — every axis inspected against primary evidence, nothing at either bar. CLEAN claims only the axes above and the files on the Inspected line, and it is wrong if a defect is later found in them.

Not a review: LGTM; restating what the change does; cosmetic findings only; reading the changed lines without the code they call.