Table of Contents

1. Product Overview
2. System Architecture
3. User & Access Management
4. Costing & Calculations
5. Invoice Management
6. Claims Management
7. Security & Authentication
8. Integrations & Data Flow
9. Configuration & Deployment
10. Common Issues & Troubleshooting
11. Best Practices

1. Product Overview

Q: What is FAP (Freight Audit & Payment)?

A: FAP is an enterprise platform within the Freehand ecosystem that automates freight audit and payment workflows. It provides end-to-end management of logistics operations including master data governance, carrier rate management, shipment cost calculations, invoice reconciliation, and claims processing.

Q: What are the core capabilities of FAP?

A: FAP delivers:

Master Data Management — Centralized management of users, vendors, carriers, locations, zones, routes, and configurations

Rate Management — Contract creation, rate card uploads, accessorial charges, fuel surcharges,

and tax configurations

Cost Computation — Automated freight cost calculations using contracts, tariffs, and rate rules

 Invoice Processing — Invoice creation, matching, reconciliation, approval workflows, and payment processing

 Claims Management — Billing dispute capture, approval workflows, and settlement processing

 ERP Integration — Posting approved invoices and payments to enterprise systems

Q: Who are the primary users of FAP?

A:

 Logistics Operations — Managing shipments, carriers, and locations

 Finance/AP Teams — Processing invoices, managing payments, handling claims

 Contract Managers — Setting up carrier contracts and rate cards

 System Administrators — Managing users, roles, and configurations

 Carriers/Vendors — Accessing vendor portal for onboarding and invoice submission

Q: What technology stack does FAP use?

A:

 Backend: Node.js 22.8.0+, Fastify framework

 Database: PostgreSQL (Sequelize ORM), MongoDB for specific data

 Caching/Queues: Redis, Bull for background job processing

 Frontend: Vue.js 3 with Vite build system, Element Plus components

 Cloud Services: AWS S3 (file storage), AWS SES (email delivery)

 Authentication: JWT-based with SAML 2.0 SSO support

Q: How does FAP relate to other Freehand services?

A: FAP is a core module of the Freehand Enterprise platform, serving as the authoritative source for freight audit and payment operations. It integrates with TMS (Transportation Management System) for shipment data, Procure for contract synchronization, and external ERP systems for financial posting.

The platform shares common master data services and authentication infrastructure with other logistics modules.

2. System Architecture

Q: How is FAP architected?

A: FAP follows a modular microservices architecture with three core service groups:

1. API Services — Handle user-facing REST API requests (Fastify-based)
2. Doer Services — Background job processors consuming from Redis/Bull queues
3. Read Services — Optimized read-only APIs for internal service-to-service calls

Q: What are the main services running in FAP?

A:

 MDM API/Auth/Email/SSO Services — Master data and authentication

 Rate Manager API/Doer/Report Services — Rate and contract management

 Costing API/Invoice/ERP Posting/SQS Services — Cost calculation and invoice processing

 Frontend UI — Vue.js-based web applications

Q: How do the services communicate?

A:

 Synchronous: REST API calls with internal authentication tokens

 Asynchronous: Redis/Bull queues for background job processing

 Shared Libraries: Common Freehand packages for authentication, S3, logging, and costing calculations

Q: What is the data flow in FAP?

A:

Master Data (Carriers, Locations, Users)

↓

Rate Contracts & Tariffs

↓

Shipment Cost Calculation

↓

Invoice Matching & Reconciliation

↓

Approval Workflows

↓

ERP Posting & Payment

Q: Why is the architecture split into API, Doer, and Read services?

A: This separation optimizes for different workload patterns. API services handle interactive user requests with authentication and validation. Doer services process long-running background jobs (bulk

uploads, costing calculations, email dispatch) without blocking user requests. Read services provide high-performance, read-only data access for internal service-to-service calls, enabling e  cient data retrieval without the overhead of full API request processing.

Q: How does the chain-based processing pattern work in costing?

A: The Elegant Costing Library uses a handler chain pattern where each handler processes a specific aspect of cost calculation: BaseFreight → FilterCostingFields → AccessorialCharges → SpotCharges

→ ExecuteCostingFields. This design allows extensibility—new charge types can be added as new handlers without modifying existing logic. Each handler receives the shipment context, applies its calculations, and passes enriched data to the next handler in the chain.

Q: What is the purpose of contract caching?

A: Contract data is cached in Redis to avoid repeated database queries during high-volume costing operations. The @Freehand/rm-contract-cache-wrapper manages cache keys based on carrier, client, and route information. Cache expiration ensures rate changes propagate within a reasonable timeframe. This design significantly improves costing performance when processing thousands of shipments.

3. User & Access Management

Q: How are users created and onboarded?

A:

1. Administrator creates user with email, name, and role assignments
2. System creates user record with PENDING status
3. Encrypted PII stored in separate secure table

N. Invitation email sent with password setup link

U. User sets password and status updates to ACTIVE

6. First login generates JWT token for session

Q: What is the role-based access control (RBAC) model?

A:

Users are assigned to Roles

Roles contain bundles of Permissions

Permissions are granular (e.g., view_invoice , approve_invoice , upload_contracts )

  Roles can be client-specific or system-wide

  Authority checker validates permissions on each API request

Q: What user-related permissions exist?

A: Common permissions include:

    view_carrier , create_carrier , view_location , manage_users

 view_contracts , upload_contracts , manage_rates , view_charges  view_costing , upload_costing , view_invoice , approve_invoice ,

view_claims

Q: How does password management work?

A:

  Password policies enforced (complexity, expiration)

 Forgot password flow sends reset email with secure token  Passwords hashed with secure algorithms before storage  Session management with configurable timeout

Q: Can users have multiple roles?

A: Yes, users can have multiple role assignments within a client context via the UserRole table. When a user has multiple roles, their effective permissions are the union of all permissions from their assigned roles. The authority checker evaluates all roles when validating access.

Q: Why is user PII stored in a separate encrypted table?

A: The UserPii table uses AES-256 encryption to protect sensitive personally identifiable information (name, email, contact details) separately from the core Users table. This separation follows the principle of least privilege—the core user table contains only operational data needed for authentication and authorization, while encrypted PII is accessed only when necessary and decrypted on-demand.

Q: How does Sendbird integration work for user chat?

A: When chat functionality is enabled, a Sendbird user record is automatically created during user onboarding. The SendBirdChatUsers table links platform users to their chat identities, enabling seamless communication within the platform. This integration is optional and configured per client.

4. Master Data Management

Q: What master data does FAP manage?

A:

Users — Platform users with roles and permissions

Vendors/Carriers — Carrier records with SCAC codes, service types, and contact details. 

Locations — Addresses, coordinates, time zones, working days, dock configurations. 

Zones — Geographic zones for rate application and service areas

Routes — Origin-destination pairs with service parameters

Currency — Currency codes with conversion rates

Fuel — Fuel price indices for surcharge calculations

Holidays — Holiday calendars by country/region/client

Q: How do I onboard a new carrier?

A:

1. Submit carrier data via API or bulk Excel upload
2. System validates data and checks for duplicates
3. Vendor record created with global attributes

N. VendorAssociation links vendor to specific client

U. Service type associations configured

1. Optional: Vendor portal user created with credentials
2. Onboarding email sent to vendor

Q: What's the difference between Vendor and VendorAssociation?

A:

 Vendor — Global entity with attributes that apply across all clients (name, registration, status)

 VendorAssociation — Client-specific relationship with carrier name, reference ID, SCAC code, custom terms

This separation allows a single vendor entity to have different business relationships, pricing terms, and operational parameters per client while maintaining a single source of truth for vendor identity.

Q: How does location geocoding work?

A: If coordinates aren't provided during location creation, a background job fetches them using Google Maps or OpenStreetMap integration. The LOCATION_LAT_LON_FETCHER queue job processes geocoding requests asynchronously, ensuring location creation isn't blocked by external API calls.

Coordinates are stored with the location for distance calculations and zone mapping.

Q: How are zones used in FAP?

A: 

Zones enable:

 Rate Application — Apply specific rates based on geographic zones

 Service Areas — Define service coverage areas

 Accessorial Charges — Apply zone-based accessorial pricing

- Zone mappings link locations/zipcodes to zones automatically

Q: How do I manage currency conversions?

A:

Currency master maintains codes, symbols, and decimal precision.

Conversion rates stored with effective dates

Historical rates available for audit

Bulk import supported from external sources

Q: Why does FAP support multiple address types per location?

A: The LocationAddress table allows locations to have separate addresses for shipping, billing, and operational purposes. This design accommodates real-world scenarios where a facility may have different addresses for different functions—for example, a warehouse may have a shipping dock address different from its billing address. This separation ensures accurate rate application and invoice generation.

Q: How do working days and holiday calendars affect operations?

A: Working days configuration in LocationsWorkingDays combined with holiday calendars enables accurate transit time calculations and scheduling. The system considers location-specific operating hours and regional holidays when computing delivery dates and service windows. This is critical for accessorial charges like detention, which depend on actual working days rather than calendar days.

Q: What is the purpose of dock management in locations?

A: Dock stations and slots enable facility scheduling and capacity management. Dock configurations define available stations, time windows, and recurring schedules. This data supports advanced logistics operations like appointment scheduling and dock utilization optimization, though the core FAP functionality primarily uses this for operational context in costing and invoice processing.