Table of Contents

1. Product Overview
2. System Architecture
3. Sourcing Event Management
4. Counter-Offer Negotiations
5. Vendor Allocation & Awarding
6. Post-Bid Optimization & Scenario Planning
7. Email Collaboration Agent
8. Approval Workflows
9. Quote Configuration
10. Event Gating
11. Notifications
12. Configuration & Deployment
13. Common Issues & Troubleshooting
14. Best Practices

1. Product Overview

Q: What is Procure Service?

Answer: Procure Service (Event Horizon) is Freehand's next-generation Freight Procurement Platform designed to manage the complete sourcing event lifecycle for transportation services. It enables shippers to create and manage sourcing events, invite vendors to bid on transportation lanes, evaluate quotes, negotiate through counter-offers, and optimize vendor allocations using scenario planning. It supports multiple transportation modes (Road, Ocean, Air) and delivery types (FTL, LTL, FCL, LCL) with configurable pricing structures and approval workflows.

Q: What are the core capabilities of Procure?

Answer: Procure delivers:

Sourcing Event Management — Create, schedule, and manage RFQ, Bid/Auction, and Spot events with lifecycle tracking

Lane Management — Define and configure transportation lanes with source/destination pairs and contract parameters

Vendor Bidding — Vendor quote submission with base freight rates, tiered pricing, and

accessorial charges

Counter-Offer Negotiations — Automated counter-offer generation and vendor negotiation workflows

Vendor Allocation & Awarding — Configure vendor allocations and sync awarded contracts to Rate Manager

Post-Bid Optimization — Scenario planning with AI-powered optimization for vendor allocation decisions

Email Collaboration — Email-based quote submission and processing from vendors

Approval Workflows — Multi-level approval configurations for event and award decisions

Q: Who are the primary users of Procure?

Answer:

Shippers — Creating sourcing events, configuring lanes, evaluating quotes, sending counter- offers, optimizing allocations

Vendors/Carriers — Receiving invitations, submitting quotes, responding to counter-offers,

receiving awards

Operations Teams — Managing event lifecycle, monitoring bidding activity, processing allocations

Finance Teams — Reviewing quote comparisons, approving award decisions

System Administrators — Configuring quote parameters, managing templates, setting up approval workflows

Q: What technology stack does Procure use?

Answer:

Backend: Node.js 18.0.0+, Fastify framework

Database: PostgreSQL (metadata + transactions databases), Sequelize ORM

Caching/Queues: Redis, Bull for background job processing

Frontend: Vue.js 3.3.4 with Vite 3.2.10, Element Plus 2.3.3, Pinia 2.0.33

Cloud Services: AWS S3 for file storage

Service Discovery: Consul

Authentication: JWT-based with @Freehand/core-logistics-auth-proxy

Mapping: Leaflet 1.9.3 for maps, ApexCharts 4.0.0 for visualization

Messaging: Sendbird Chat SDK for vendor communication

Q: How does Procure relate to other Freehand services?

Answer: Procure is the procurement layer that feeds into Rate Manager for contract execution. Awarded vendor allocations are synced to Rate Manager as contracts, enabling seamless transition from sourcing to rate management. Procure integrates with Core-Logistics Common Masters for vendor and location data, and can trigger downstream processes in TMS for shipment execution using awarded rates.

2. System Architecture

Q: How is Procure architected?

Answer: Procure follows a modular microservices architecture with the following components:

1. Procure API Service ( procure-api-service.js ) — Primary REST API service for shipper and vendor operations (port 4040)
2. Procure Doer Service ( procure-doer-service.js ) — Background job processor for async operations like lane uploads and vendor bidding (port 4050)
3. Transaction Doer Service ( transaction-doer-service.js ) — Background processor for transaction-heavy operations like quote processing and optimization (port 4051)

N. Frontend UI — Vue.js 3 SPA with Element Plus components and Pinia state management

U. Shared Packages — procure-constants, procure-errors, procure-common-lib, procure-local-cache,  procure-redis.

Q: What routes are available in the API service?

Answer:

Shipper Routes: Prefixed with /fns/api for shipper-facing operations (event creation, lane management, quote evaluation, allocation)

Vendor Routes: Prefixed with /fnv/api for vendor-facing operations (quote submission, counter-offer response, event access)

Q: How do the services communicate?

Answer:

Synchronous: REST API calls with JWT authentication

Asynchronous: Redis/Bull queues for background job processing

Shared Libraries: procure-constants for enums, procure-errors for error definitions

Service Discovery: Consul for dynamic endpoint resolution

Q: What is the high-level data flow in Procure?

Answer:

Event Creation → Lane Configuration → Vendor Invitation

↓

Vendor Quote Submission → Quote Validation & Scoring

↓

Counter-Offer Negotiations (optional)

↓

Post-Bid Optimization & Scenario Planning

↓

Vendor Allocation & Awarding → Contract Sync to Rate Manager

Q: Why are there separate metadata and transactions databases?

Answer: The metadata database stores event configuration, settings, lanes, and vendor associations— relatively static data that changes infrequently. The transactions database stores quote submissions, optimization jobs, and timeline entries—high-volume transactional data. This separation enables independent scaling, optimized query performance, and cleaner data management. Transaction-heavy operations don't impact metadata queries, and each database can be tuned for its workload pattern.

Q: Why is the Transaction Doer service separate from the Procure Doer?

Answer: The Transaction Doer handles compute-intensive operations like quote scoring, optimization jobs, and bulk quote processing that require significant CPU and memory resources. Separating it from the Procure Doer (which handles lighter async tasks like notifications and lane uploads) enables independent scaling and resource allocation. This design prevents heavy optimization jobs from blocking lighter operations and allows each service to be scaled based on its specific workload.

Q: What is the purpose of shared packages?

Answer: Shared packages ( procure-constants, procure-errors , procure-common-lib ) provide common definitions and utilities used across all Procure services. This ensures consistency— event statuses, error codes, and business logic are defined once and shared. The packages prevent duplication, enable centralized updates, and maintain type safety across the microservices architecture.