Integration architecture
Edge Portal is a product on the Kaptio Edge Platform — the same production platform that operates Edge Docs, Edge Pay, and Edge Journeys. The portal service itself holds no booking data: every trip, payment, document, and form a traveler sees is resolved at request time by a provider, and which provider a portal runs on is one line of tenant configuration.
Mock provider
provider: mock serves a complete, internally consistent seeded world from in-platform fixtures — trips, itineraries, payment schedules, transactions, documents, forms with fields and saved answers, and optional extras. It exists so a portal can be evaluated end to end (including magic-link sign-in and per-traveler data scoping, which apply exactly as in production) before any upstream system is connected. Tenant isolation and traveler scoping are structural in the mock too: a session only ever sees trips its traveler appears on, within its own tenant.
Live provider
provider: live resolves the same provider interface against real systems. It requires live.sf_environment in the portal's configuration — the Salesforce environment the traveler data lives in.
| Data | Upstream |
|---|---|
| Traveler identity (magic-link issuance) | Edge Admin Backend identity lookup — returns existence and display identity only, never booking data |
| Trips, passengers, itinerary days, payment schedules, payment transactions, optional extras | Edge Admin Backend traveler-lookup routes, which read from the tenant's Salesforce org through the platform's centralized OAuth |
| Documents | Edge Admin Backend, sourcing published Edge Docs documents — already recipient-scoped and filtered to sent, unexpired documents |
| Pre-departure forms (definitions, answers, submissions) | Webform API, the platform's forms service |
Two authentication layers travel on every live lookup:
- A shared internal service key between the portal and its upstreams — the same mechanism other Edge products use for internal calls.
- The traveler's own portal session token, forwarded and re-validated by the upstream, so a service-key holder can only ever read the authenticated traveler's data. Ownership is enforced again at the source: a traveler resolves only itineraries they appear on, and sub-resource requests for other trips come back empty.
The identity lookup used during magic-link issuance is the one exception — no session exists yet, so it runs on the service key alone against a route that returns display identity only, and only for guest-type portals.
The Salesforce-backed upstreams in the table above are the current shipped realization of the live provider (provider: live requires live.sf_environment). Reservation systems outside Salesforce are not a second live-provider type in portal.yaml: they are onboarded through a platform-built per-tenant adapter, agreed in the interface contract, that supplies the canonical booking feed — pushed on change or pulled on a schedule, per the data contracts — and receives the write-back events. That adapter maps onto the same provider interface, so the portal service and /api/portal/v1 stay unchanged. The mock provider proves the portal side of that interface with fixtures; it is not itself a production feed or write-back adapter.
When an upstream is unreachable or fails, the portal responds 502 with a stable code (UPSTREAM_UNREACHABLE / UPSTREAM_ERROR) and never leaks upstream status or detail to the traveler-facing client. An environment with no forms upstream configured simply exposes no forms rather than erroring.
Where the data contracts fit
The data contracts page specifies the canonical reference model — the booking feed the portal renders from and the events guest actions produce. The provider seam is where that model is realized: the mock provider ships it as seeded fixtures, and the live provider maps it from your systems through the platform's existing integration surfaces (Salesforce via the Admin Backend's centralized OAuth, Edge Docs, Webform API). Per-tenant mappings from your reservation system's payloads onto the canonical shapes are agreed in the interface contract during implementation workshops.
Observability
The service follows the platform's observability baseline:
- Structured JSON logs to stdout, with stable event names (
portal_upstream_error,portal_ui_build_failed,portal_config_invalid, ...) and tenant/portal context on every event — collected by the platform log pipeline. - Prometheus metrics on a separate, cluster-internal metrics port (never on the public listener): request counts and latency histograms labelled by method, normalized path, and status, plus process defaults.
- Health endpoints
/healthand/readyat the service root for orchestration probes.
Upstream calls are individually logged with target service, status, and duration, so a slow Salesforce lookup or a failing forms upstream is attributable from the platform's dashboards without touching traveler data.