ADR-002: ESL Button Press Domain Events

Context

The ESL webhook integration currently lives in the v1 API handler (v1/external/solum/handler.go). The handling of our internal shop system is directly wired into it. This was fine when our product was an MVP. With the first third-party integrations right around the corner, we need a way to notify them of button press events.

Decision

Create a new NATS JetStream esl. Transition to publishing incoming button press webhooks on a subject like button.pressed.

Example protobuf message

message ESLButtonPressEvent {
    string org_id = 1;
    string label_id = 2;
    string label_code = 3;
    ButtonType button = 4;
    google.protobuf.Timestamp ts = 5;
}

enum ButtonType {
    REQUEST = 1;
    REFILL = 2;
}

Alternatives considered

We didn't consider any alternatives as NATS JetStream is the established tech for durable async messaging.

Consequences

• Allows other modules and third-party integrations to consume ESL events and build behavior on top of it
• The OrderService will no longer be called directly and instead subscribes to the button press stream
• Improves durability ESL button presses received as webhooks
• Introduces a bit of delay into the system, especially during high traffic (not an issue right now)

Migration Path

• rename solum module to esl
• introduce new endpoint in esl
  • /api/v2/external/esl/solum/webhook (they only support one per tenant anyway)
  • this endpoint will publish new button presses to NATS
• let run in parallel for one release
• switch over all tenant webhooks in solum
• remove old endpoint and logic