---
arc42: "3 — Context and Scope"
status: stub
---

## 3.1 Business Context

TODO: PlantUML system context diagram.

External actors:
- **Autonomous Agent** — queries the index by capability; reads BSM; consumes registered services
- **Service Registrant** — submits BSM via portal or API; receives registration confirmation
- **Spider** — automated crawler (internal); checks liveness of registered services against external endpoints
- **Admin (BSF)** — assigns O-levels; approves pending registrations; monitors registry health
- **External Service Endpoints** — the actual services being registered; queried by Spider for liveness

```plantuml
@startuml context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(agent, "Autonomous Agent", "Queries registry by capability; consumes registered services")
Person(registrant, "Service Registrant", "Submits BSM; monitors registration status")
Person(admin, "BSF Admin", "Assigns O-levels; approves registrations")

System(apix, "APIX Registry", "Global, queryable index of machine-consumable services")

System_Ext(ext_service, "External Service Endpoint", "The registered service; queried by Spider for liveness")

Rel(agent, apix, "Capability query / BSM fetch", "HTTPS/JSON")
Rel(registrant, apix, "BSM registration / status check", "HTTPS/JSON or Portal")
Rel(admin, apix, "O-level assignment / moderation", "Portal (API-key)")
Rel(apix, ext_service, "Liveness check / spec fetch", "HTTPS", "Spider")

@enduml
```

## 3.2 Technical Context

TODO: PlantUML technical context diagram showing network boundaries.

Components inside the system boundary:
- Caddy (reverse proxy, TLS termination)
- API service (FastAPI)
- Portal service (FastAPI + HTMX)
- Spider service (async Python scheduler)
- PostgreSQL (registry database)

## 3.3 External Interface Table

| Interface | Direction | Protocol | Data |
|---|---|---|---|
| Capability query | Agent → API | HTTPS GET | Query params: `capability`, `country`, `olevel`; Response: BSM list |
| BSM registration | Registrant → API | HTTPS POST | BSM JSON payload + API key header |
| Service detail | Agent → API | HTTPS GET | BSM + liveness status |
| HATEOAS root | Agent → API | HTTPS GET | Navigation links JSON |
| Liveness check | Spider → Ext. service | HTTPS GET | HTTP status + response time |
| OpenAPI fetch | Spider → Ext. service | HTTPS GET | OpenAPI JSON spec |
| Admin portal | Admin → Portal | HTTPS | Browser; HTML form |