Multi event handling & terminal registration

Requirements regarding multiple events.

Support for multiple events
Each event should have multiple editions (e.g. Summerdays 2025, Summerdays 2026, etc.)
Customer site
- Each event should have a separate customer site that will handle the current event edition, and should support handling data from previous editions.
- Customer profile should be created for each event, and should not be shared between events.
Admin site
- There should be a single admin site that can handle multiple events and editions.
- Admin site users should be global (can be used for multiple event editions if authorized).
- Admin site roles should be assigned to users at eevent edition level, so that users can have different roles for different event editions.
- Most admin site functionality is limited to a selected event edition. Only a few global functionalities are available across all event editions. (e.g. user management, event management, Merchants??, etc.)
- An event edition selector should be available on the admin site to select the current event edition for which the admin site is used.

Limitations in current phase

In this phase we support multiple events and only a single event edition for each event. (later multiple editions will be supported for each event)
On customer site only the current event edition is supported, previous editions are not available.

Handling on Admin site

Admin site API calls

Most API calls require an event edition expect a few global ones.

The frontend should ensure that all API calls that require an event edition will include this header.
The backend should ensure that all API calls that require an event edition will check this header and use the event edition id to filter the data, and check authorization for that event edition. If the header is not present, the backend should return an error.
At the backend the eventEditionId should be added to all entities (tables) that is related to an event edition and a global filter should be applied, so that only data for the selected event edition is returned.
Grid queries should also handle weather event edition is required or not and apply filter accordingly. This needs nore design!!

We have to mark each call if the header is required or not. If possible create an interceptor that will check the header and filter the data accordingly based on method option retrieved from grpc metadata.

shared.proto:

extend google.protobuf.MethodOptions {
  bool requires_event_edition = 5000;
}

service AcLogicalType {
  rpc GetForView(shared.IdDTO) returns (AcLogicalTypeGetForViewResponseDTO) {
    option (requires_event_edition) = true;
  };

The GRPC API calls will use the following header:

X-GadgetFest-EventEditionId: <event edition id>

Integration webhooks

Preferred way to handle webhooks is to use the event edition id in the webhook URL, so that the backend can extract it from the URL and use it to filter the data. This is the safest way to ensure that the webhook is processed for the correct event edition. In case it is not possible to configure multiple webhooks for each event edition, we can use a single webhook URL pick event edition based on some identifier in the payload. We can not guarantee that the integration can send us our header X-GadgetFest-EventEditionId, so we should encode the event edition id in the webhook URL, so that the backend can extract it from the URL and use it to filter the data.

Handling on Customer site

Customer site will show data from the current event edition only (later we will support showing data from previous editions as well.)

Customer Site API calls

The GRPC API calls will use the following header:

X-GadgetFest-EventId: <event id>

The frontend should ensure that all API calls will include this header.
The backend should ensure that all API calls will check this header and use the single event edition id defined for the event to filter the data. The Entra ID tenant to check authorization should be the one assigned to the event in configuration or database. If the header is not present, the backend should return an error.
At the backend the eventEditionId should be added to all entities (tables) that is related to an event edition and a global filter should be applied, so that only data for the selected event edition is returned. The customers table should have eventId FK.

Handling on Terminal

The terminals should be identified by a terminalId that is unique for the whole system, that id will be generated at registration time, and should never change.

The terminals have a database that should be initialized when the terminal is assigned to an event edition. The database should contain internally the terminalId, eventEditionId, assignmentId and the name of the database file should also contain all three identifiers, so that it is clear which terminal and which event edition the database belongs to. The currently used database file name should be stored in a plain text or json file, together with the terminalId.

Terminal API calls

The GRPC API calls will use the following headers (only exception is the registration call, what will be different):

X-GadgetFest-TerminalId: <terminal id>
X-GadgetFest-AssigmentId: <assignment id>
X-GadgetFest-EventEditionId: <event edition id>
X-GadgetFest-Authorization: <authorization token, PSK>

The terminal should ensure that all API calls will include these headers.
The terminals should be identified by the terminalId and authorization should be checked based on authorization token assigned to the identified terminal.
The backend should ensure that all API calls will check these headers and use the event edition id to filter and store data. If any of the headers is not present, the backend should return an error.
The backend should check the ids to be in sync with the database, (state of terminal, assigned event edition, and assignment id).
At the backend the eventEditionId should be added to all entities (tables) that is related to an event edition and a global filter should be applied, so that only data for the selected event edition is returned.

Terminal registration

Registering a terminal is a one time process, after that it can be used for multiple event editions. Steps to register a terminal:

Create a terminal on the admin site, this will generate a terminalId and a uniq 6 digit registration number and store it in the database.
The registration number can be used a single time to register the terminal.
At the terminal enter the registration number, the terminal generates a PSK and sends it to the backend together with the terminalId to complete the registration.

Physical identifiers like MAC address or serial should not be used to lookup the existing terminal in the database, lookup can also happen based on terminalName what is also globally unique. During registration a new certificate is generated in the terminal, stored in secure store on android, a CSR is generated and sent to the backend for signing.

10 July 2025