ordr (v1.0.0)

A backend service that uses temporal features to manage order orchestration, like sending and receiving events related to the order processing flow. Exposes GraphQL APIs for external mobile app integration and internal cluster services.

Service OpenAPI

Service Overview

The ordr service is a comprehensive order orchestration system built with Go and Temporal workflows. It manages the complete order lifecycle from creation to fulfillment, including payment processing, fraud detection, and integration with multiple external systems.

Key Features

  • Order Lifecycle Management: Complete order processing from creation to fulfillment
  • Payment Processing: Integration with Daki payment system for PIX, card, and digital payments
  • Fraud Detection: Advanced fraud detection capabilities for payment security
  • Multi-System Integration: Seamless integration with BTLR, Ticketer, iFood, and other systems
  • Workflow Orchestration: Temporal-based workflows for reliable order processing
  • Data Export: Automated data warehouse exports for analytics and reporting

Architecture Components

Core Workflows

  • Order Lifecycle: Main order processing workflow
  • Payment Flow: Payment status updates and processing
  • Restore Flow: Order restoration for failed processes
  • Integration Flows: External system integrations

Integration Systems

  • BTLR Integration: Business transaction layer integration
  • Ticketer Integration: Customer support ticket management
  • iFood Integration: Food delivery platform integration
  • 2PL Integration: Second-party logistics integration
  • Tray Integration: Point-of-sale system integration
  • Braze Integration: Customer engagement platform
  • Kustomer Integration: Customer service platform

Specialized Flows

  • Fraud Detection: Payment fraud detection and prevention
  • Catalog Processing: Product catalog management
  • Slot Management: Delivery slot management
  • User Profile: Customer profile management
  • Delivery Management: Raio delivery integration
  • Notification Management: Braze notification system

Event Architecture

The service operates on a comprehensive event-driven architecture with:

  • Input Channel: Receives commands and triggers
  • Output Channel: Publishes order events and status updates
  • Command Processing: Handles fulfill, cancel, and restore operations
  • Trigger Management: Processes various system triggers

API Specifications

The service exposes GraphQL APIs for:

  • External mobile app integration
  • Internal cluster service communication
  • Order management operations
  • Workflow status monitoring

Service Components

Commands

The service processes three main command types:

  • Fulfill: Triggers order fulfillment process
  • Cancel: Cancels an existing order
  • Restore: Restores a failed or interrupted order

Channels

  • Input Channel: Receives all incoming commands and triggers
  • Output Channel: Publishes order events and status updates

Triggers

The ORDR system uses triggers and handlers to process incoming events and manage temporal workflows. Each trigger is responsible for processing a specific type of event and executing the corresponding business logic.

1. FulfillOrdrTrigger

File: internal/app/triggers/fulfill_order_trigger.go

Responsibility: Processes order fulfillment events

  • Validates order ID
  • Obtains processing lock
  • Checks if order is already fulfilled
  • Starts or signals fulfillment workflow
  • Publishes OrdrFulfilledV1 event

Input Events:

  • FulfillOrdrTrigger - Order fulfillment trigger

Output Events:

  • ordr_fulfilled - Order fulfilled

2. DakiPaymentUpdateTriggerHandler

File: internal/app/triggers/daki_payment_update_trigger.go

Responsibility: Processes Daki payment status updates

  • Validates payment data
  • Ignores unnecessary initial statuses
  • Processes different payment types (PIX, Card, Digital)
  • Manages refund flows
  • Starts fulfillment or placement workflows

Supported Payment Statuses:

  • pre_authorized, waiting (ignored)
  • authorized, paid (processed)
  • canceled (normalized to cancelled)
  • refunded, partially_refunded, failed_refund (refund)

Input Events:

  • DakiPaymentUpdateTriggerEvent - Payment update

Output Events:

  • ordr_payment_status_update - Payment status updated
  • ordr_fulfilled - Order fulfilled (when applicable)

3. InvoiceTrigger

File: internal/app/triggers/invoice_trigger.go

Responsibility: Processes invoice creation events

  • Validates invoice data
  • Signals workflow with invoice details
  • Exports data to data warehouse

Input Events:

  • InvoiceTrigger - Invoice creation

Output Events:

  • No direct events (workflow signaling only)

4. RestoreOrdrTrigger

File: internal/app/triggers/restore_order_trigger.go

Responsibility: Processes order restoration events

  • Checks if order already exists
  • Starts restoration workflow
  • Sets default values

Input Events:

  • RestoreOrdrTrigger - Order restoration

Output Events:

  • No direct events (workflow signaling only)

Handlers and Receivers

1. SelectorHandler

File: internal/app/temporal/receivers/selector.go

Responsibility: Manages the main workflow loop

  • Coordinates all receivers
  • Manages workflow state
  • Controls workflow TTL
  • Exports data to data warehouse

2. Specialized Receivers

FulfillOrderReceiver

  • Processes order fulfillment signals
  • Executes fulfillment activities

DakiPaymentUpdateReceiver

  • Processes payment updates
  • Manages different payment types

InvoiceReceiver

  • Processes invoice creation
  • Updates order state

RefundReceivers

  • Processes refund requests
  • Manages refund status

Processing Flow

1. Event Reception

Event → Trigger → Validation → Lock → Processing

2. Workflow Processing

Trigger → Signal/Start Workflow → Receiver → Activity → State Update

3. Event Publishing

State Update → Publisher → PubSub Topic → Downstream Services

Implementation Patterns

1. Lock Service

  • Prevents concurrent processing
  • Uses GCS bucket for locks
  • Automatic timeout

2. Error Handling

  • Automatic retry for locks
  • Graceful degradation
  • Structured logging

3. Data Warehouse Export

  • Asynchronous export
  • Structured data
  • Retry on failure

Configuration

Workflow TTL

  • Configurable per environment
  • Default: 24 hours
  • Automatic extension

Lock Timeout

  • Configurable per trigger
  • Default: 5 minutes
  • Automatic cleanup

Retry Policies

  • Exponential backoff
  • Maximum attempts
  • Dead letter queue

Flows

The service includes specialized flows covering:

  • Order lifecycle management
  • Payment processing
  • System integrations
  • Fraud detection
  • Delivery management
  • Customer service integration
Edit this page