Udarbejde en stabil og versioneret event-kontrakt for RecognitionCompleted. Dokumentere AI-pipelinen (Vision → Reasoning) og definere klare schemaer og metadata. Understøtte microservice-integration gennem klare kontrakter og versioneringsprincipper.

I denne uge har jeg arbejdet med at færdiggøre dokumentationen for vores udgående Kafka-event RecognitionCompleted. Formålet har været at etablere en stabil grænseflade, som andre services trygt kan bygge ovenpå.

Jeg har:

• udarbejdet et versioneret JSON-schema (v1) for eventet
• dokumenteret semantik, leveringsregler og versioneringspolitik
• tilføjet metadata for både Vision-analyse og LLM-reasoning
• opdateret servicekoden, så reasoning-providerinfo bliver flettet korrekt ind i AIProviderDto
• testet produceren med både almindelige enhedstests og snapshot-lignende valideringer af payloaden

Kontrakten er nu frosset i v1, og kræver en ny version ved breaking changes.

Versioneret RecognitionCompleted-kontrakt – v1

Eventet udstilles efter analyse af billeder og efterfølgende reasoning (hvis aktiveret). Kontrakten er stabiliseret som recognition.completed.v1 og beskriver både Vision-output og (valgfrit) reasoning-output.

Uddrag fra kontrakten:

Provider-metadata inkl. LLM reasoning

I v1 indeholder provider nu både:

• Vision-metadata (navn, model, features)
• Reasoning-metadata (reasoningName, reasoningModel)

Dette afspejler den faktiske pipeline: Vision → Aggregation → (Optional) Reasoning → Event

Kodeopdatering i RecognitionService:

Her kan man se at reasoning kan blive slået til, hvor man vil berige resultatet med yderligere metadata ved brug af den valgte LLM. Der vil desuden tilføjes ny information om AIProvider da LLM model er en anden end den der bliver brugt til billedgenkendelse.

JSON-schema (v1)

Jeg har udarbejdet et JSON-schema, der beskriver strukturen for payloaden. Schemaet er tænkt som:

• dokumentation
• værktøj til validering
• kontrakt mellem microservices

Schema-uddrag:

Producer-test og payload-validering

Jeg har testet:

• header-opbygning (x-schema, x-producer, x-correlation-id)
• key-strategi (objectKey)
• serialisering via IKafkaSerializer

Testeksempel:

Denne dokumentationsopgave har givet mig en dybere forståelse for, hvordan API-kontrakter og event-schemaer fungerer som rygraden i en microservice-arkitektur.

Jeg har fået erfaring med:

• kontraktversionering (v0 → v1)
• udarbejdelse af JSON-schemaer som formelle kontrakter
• integration mellem Vision AI og reasoning via AIProviderDto
• kommunikation af tekniske designvalg til andre udviklere
• messaging-semantik (ordering, correlation, at-least-once levering)

Samlet set har arbejdet styrket min kompetence til at designe backend-løsninger, der er både robuste, udskiftelige og forståelige for andre teams.