Aktivitetsflyt: Slik sporer vi hele bookingkjeden

Et bookingsystem kan virke enkelt utenfra. Kunden velger tid, betaler og får tilgang. Men under panseret involverer en enkel booking flere systemer som samhandler asynkront. Nettleseren snakker med APIet, APIet snakker med betalingstjenesten, og minutter senere kommer det en webhook tilbake. Hvis noe feiler, hvordan finner du ut hvor det gikk galt?

Problemet med uavhengige hendelser

Uten korrelasjons-ID viser admin-loggen kun løsrevne hendelser:

• Betaling opprettet kl 14:32:05
• Booking opprettet kl 14:32:07
• Betaling fullført kl 14:32:45
• Tilgangskode sendt kl 14:32:47

Disse hendelsene henger åpenbart sammen, men systemet behandler dem som separate events. Hvis betalingen feiler, må administratoren manuelt krysse-referere tidspunkter og kunde-IDer for å forstå hva som skjedde. Det tar tid og fører til feil.

Løsningen: Correlation-based distributed tracing

Vi bygget aktivitetsflyt som en distribuert sporingsarkitektur basert på korrelasjons-IDer. Hver brukerreise får en unik correlationId som følger alle relaterte hendelser gjennom hele systemet.

Når en booking startes, genereres en correlationId på formatet:

booking-m1abc123-x7y8z9

Dette er et menneskevennlig format. I motsetning til UUIDer kan du umiddelbart se hva slags flyt det er. Det første segmentet angir flyttype, andre segment er tidsstempel i base36, tredje segment er tilfeldig.

Flyten krysser asynkrone grenser

Det geniale med aktivitetsflyt er at correlationId overlever asynkrone brudd. Her er hvordan det fungerer:

1. Kunden trykker "Bekreft booking" i nettleseren
2. API-ruten genererer correlationId: booking-m1abc123-x7y8z9
3. Booking intent opprettes med correlationId
4. Betaling initieres hos Vipps/Stripe
5. correlationId lagres i payment.metadata{"correlationId": "booking-m1abc123-x7y8z9"}
6. Kunden omdirigeres til Vipps for betaling
7. [Minutter går, brukeren betaler]
8. Vipps webhook treffer serveren
9. Webhook-handleren leser correlationId fra payment.metadata
10. FORTSETTER den samme flyten med samme correlationId
11. Booking bekreftes, tilgangskode sendes, alt under samme flyt

Dette betyr at en brukerhandling i nettleseren, API-rute, ekstern betalingsleverandør og webhook-callback minutter senere alle deler samme correlationId. Du får en komplett tidslinje på tvers av systemgrenser.

Åtte flyttyper

Vi støtter åtte forskjellige flyttyper, hver med sitt eget prefiks:

• booking_flow – Bruker bestiller en time
• payment_flow – Betalingsprosess alene
• session_flow – Innlogging og autentisering
• membership_flow – Medlemskapsregistrering
• renewal_flow – Automatisk fornyelse
• accounting_flow – Regnskapsavstemming
• access_code_flow – Tilgangskode-generering
• cron_flow – Planlagte jobber

FlowTracker: Fluent API for sporing

Vi bygget en FlowTracker-klasse som gir en fluent API for å logge steg i flyten:

const flow = FlowTracker.startBooking(organizationId);
// correlationId auto-generert: booking-m1abc123-x7y8z9

await flow.step('BOOKING.INITIATED', {
  resourceId: 42,
  startTime: '2025-02-10T15:00:00Z'
});

await flow.step('PAYMENT.INITIATED', {
  amount: 500,
  provider: 'vipps'
});

// Senere, når webhook kommer tilbake:
const flow = FlowTracker.continue(correlationId, organizationId);
await flow.step('PAYMENT.COMPLETED');
await flow.step('BOOKING.CONFIRMED');
await flow.step('ACCESS_CODE.SENT');

FlowTracker håndterer automatisk stegtelling, tidsstempler og logging til databasen.

Tre-tabells tidslinje-merge

For å rekonstruere en komplett brukerreise må vi merge data fra tre tabeller:

• user_activities – Generelle hendelser
• payment_transactions – Betalingsdetaljer
• booking_intents – Booking-tilstand

Vi bygget en tjeneste som slår sammen disse basert på correlationId og sorterer kronologisk. Resultatet er en komplett tidslinje som viser alt som skjedde i flyten, på tvers av domener.

Admin-UI med visuell tidslinje

I admin-panelet ser du flyter som ekspanderbare kort. Hvert kort viser:

• Flyttype og correlationId
• Fargekode (grønn = fullført, rød = feilet, blå/puls = pågående)
• Vertikal tidslinje med steg
• Varighet mellom hvert steg
• Metadata for hvert steg

Du kan filtrere etter status (fullført/feilet/pågående) og flyttype. Hvis en betaling feiler, ser du nøyaktig hvilket steg som feilet og når.

Multi-tenant trygt

Alle flyt-spørringer enforcer organizationId-isolering. En admin fra organisasjon A kan aldri se flyter fra organisasjon B. Dette er bygget inn i databaselaget med row-level security policies.

Hva gjør dette spesielt

Aktivitetsflyt er ikke bare logging. Det er en distribuert sporingsarkitektur som:

• Overlever asynkrone grenser (nettleser → API → betalingsleverandør → webhook)
• Bruker menneskevennlige IDer (ikke UUIDer)
• Merger data på tvers av domener (betalinger + bookinger + aktiviteter)
• Gir visuell historiefortelling i admin-UI
• Håndterer multi-tenancy trygt

Resultatet er at når noe går galt, bruker du sekunder på å finne årsaken, ikke minutter. Og når alt går riktig, har du en komplett audit-logg over hele brukerreisen.

Teknisk stack

Implementasjonen bruker:

• PostgreSQL for lagring med JSONB-metadata
• Row-level security for multi-tenant isolering
• Prisma ORM for type-sikre spørringer
• React Server Components for admin-UI
• Tailwind for styling av tidslinjer

Hele systemet er type-sikkert fra database til UI. TypeScript validerer at correlationId-formatet er korrekt, at metadata matcher flowtype og at stegtelleren inkrementeres monotont.

Aktivitetsflyt er et eksempel på hvordan god teknisk arkitektur gir bedre debugging, bedre support og høyere pålitelighet. Det kostet tid å bygge, men sparer oss for timer hver uke når vi skal feilsøke kundehendelser.