---
arc42: "6 — Runtime View"
status: stub
---

## Scenario 1 — Agent Queries Registry by Capability

```plantuml
@startuml sc1
actor Agent
participant "Caddy" as caddy
participant "API Service" as api
database "PostgreSQL" as db

Agent -> caddy : GET /api/services?capability=inventory.read&country=DE
caddy -> api : forward
api -> db : SELECT services WHERE capability MATCH AND country=DE AND liveness=live
db --> api : [ServiceRecord, ...]
api --> caddy : 200 OK — JSON array of BSM summaries with _links
caddy --> Agent : response

@enduml
```

## Scenario 2 — Service Registrant Submits BSM via Portal

```plantuml
@startuml sc2
actor Registrant
participant "Caddy" as caddy
participant "Portal Service" as portal
participant "API Service" as api
database "PostgreSQL" as db

Registrant -> caddy : POST /register (form submit)
caddy -> portal : forward
portal -> api : POST /api/register (BSM JSON + API key)
api -> api : validate BSM (Pydantic)
alt BSM invalid
  api --> portal : 422 Unprocessable — validation errors
  portal --> Registrant : form with errors highlighted
else BSM valid
  api -> db : UPSERT service record
  db --> api : service_id
  api --> portal : 201 Created — service_id + status URL
  portal --> Registrant : "Registered. Status: pending O-level."
end

@enduml
```

## Scenario 3 — Spider Liveness Check

```plantuml
@startuml sc3
participant "Spider Scheduler" as sched
participant "Fetcher" as fetcher
participant "Evaluator" as eval
participant "DB Writer" as writer
database "PostgreSQL" as db
participant "External Service" as ext

sched -> db : SELECT services WHERE next_check <= NOW()
db --> sched : [ServiceRecord, ...]
loop for each service
  sched -> fetcher : check(service_url, spec_url)
  fetcher -> ext : GET service_url (timeout: 5s)
  ext --> fetcher : HTTP response
  fetcher -> eval : (status_code, response_time_ms)
  eval --> writer : liveness=live|degraded|unreachable, checked_at=NOW()
  writer -> db : UPDATE liveness_status WHERE service_id=X
end

@enduml
```

## Scenario 4 — Agent Navigates via HATEOAS

```plantuml
@startuml sc4
actor Agent
participant "API Service" as api

Agent -> api : GET /api/
api --> Agent : 200 OK — { "_links": { "search": "/api/services{?capability,country}", "register": "/api/register", "health": "/api/health" } }

Agent -> api : GET /api/services?capability=slot.book
api --> Agent : 200 OK — [{ "id": "...", "name": "...", "_links": { "self": "/api/services/{id}" } }, ...]

Agent -> api : GET /api/services/{id}
api --> Agent : 200 OK — full BSM record + liveness status

@enduml
```