Skip to main content

Delivery Marketplace Provider Port

Source-backed guide for the delivery marketplace provider contract in apps/backend/src/delivery-marketplace/domain/delivery-marketplace-provider.port.ts.

Use this when adding providers (Uber Eats, Rappi, etc.) or deciding whether a change belongs in the domain port, application use cases, infrastructure adapter, or HTTP interface.

Intent​

The delivery marketplace module connects a FlowPOS restaurant location to third-party delivery platforms so merchants can:

  • push menus and 86 items
  • open/close the store for marketplace ordering
  • ingest inbound orders into restaurant POS
  • accept, deny, cancel, and status-sync orders outbound

Application use cases depend only on DeliveryMarketplaceProviderPort. PedidosYa HTTP paths, OAuth token caching, and Zod payload shapes stay in infrastructure.

Current runtime provider status:

  • pedidosya is registered in MarketplaceProviderRegistry
  • uber_eats exists on the MarketplaceProvider enum but has no adapter and is not registered

Hexagonal map​

LayerCodepathsResponsibility
Domaindomain/delivery-marketplace-provider.port.ts, repository ports, domain errors/events/servicesProvider-neutral contracts, menu-mapping invariants, domain errors
Applicationapplication/use-cases/*, marketplace-connection.service.ts, marketplace-provider-registry.service.ts, order lifecycle listenerConnect/disconnect, ingest, accept/deny, menu push, store/item availability, status fan-out
Infrastructureinfrastructure/pedidosya/*, Kysely repositories, BullMQ processorsPedidosYa HTTP/auth, payload mapping, credential encryption at rest, queue workers, Redis token/lock keys
Interfacesinterfaces/delivery-marketplace.controller.ts, interfaces/webhooks/pedidosya-plugin.controller.ts, DTOs, IP allowlist guardAuthenticated merchant API and public PedidosYa webhook endpoints

Port contract​

DeliveryMarketplaceProviderPort groups provider responsibilities by workflow:

AreaMethodsNotes
ConnectiontestConnection, loginValidate credentials / obtain provider tokens
MenupushMenu, pollMenuJobFull menu push and async job polling
AvailabilitygetStoreStatus, setStoreStatus, setItemAvailabilityStore open/closed and item 86
Order writesacceptOrder, denyOrder, cancelOrder, updateOrderStatusOutbound lifecycle actions
Order readsgetOrders, getOrderReconciliation / replay

Domain value objects on the port (MarketplaceMenu, MarketplaceInboundOrder, MarketplaceCredentials, etc.) are provider-neutral. Adapters map platform JSON into these shapes; application code must not import PedidosYa schemas.

Registry registration​

MarketplaceProviderRegistry currently maps:

Provider keyAdapter
pedidosyaPedidosYaAdapter

Unsupported provider names throw MarketplaceProviderNotConfiguredError.

To add another provider:

  1. Implement an adapter under apps/backend/src/delivery-marketplace/infrastructure/<provider>/.
  2. Satisfy DeliveryMarketplaceProviderPort with provider-neutral return values.
  3. Register the adapter in MarketplaceProviderRegistry and DeliveryMarketplaceModule.
  4. Add webhook/controller routes only if the provider pushes events to FlowPOS.
  5. Extend DTOs / enums only when the new provider is selectable at connect time.
  6. Cover adapter mapping, auth, and outbound actions with tests.

Do not branch inside use cases for provider-specific payload formats. Prefer adapter-local mappers (see infrastructure/pedidosya/mappers/).

Domain vs infrastructure boundaries​

Keep in domain / application:

  • connection uniqueness per location+provider
  • ingest dedup by external order ID
  • menu mapping consistency
  • restaurant order creation and kitchen send orchestration
  • when to enqueue outbound/FEL jobs

Keep in infrastructure:

  • PedidosYa OAuth client credentials and Redis token cache
  • PedidosYa webhook Zod schemas and HTTP clients
  • BullMQ processors and Redis menu-push locks
  • IP allowlist CIDR matching for PedidosYa webhooks