FPay - Freight Payment Platform

Project Overview

FPay is a comprehensive freight payment processing platform built to streamline payment operations for freight and logistics services. The platform provides complete payment lifecycle management, invoice tracking, and advanced EDI (Electronic Data Interchange) 210 transaction processing capabilities.

What sets FPay apart is its innovative integration with Anthropic's Claude AI to automatically generate realistic freight shipment data and EDI 210 files. Instead of manual data entry, users can leverage AI to create authentic freight data including company names, addresses, realistic weights, freight charges, and all necessary EDI fields.

Timeline

November 2025 - Present

Role

Lead Developer / Architect

Type

Web Application / REST API

Status

Active Development

Tech Stack

Node.js 24 Express.js 4.18 MongoDB Atlas Mongoose 8.0 Claude AI SDK 0.32 Helmet Security Azure Web App Azure DevOps HTML5/CSS3

Development Metrics

Commits

Data Models

Shipment Types

10+

Admin Pages

Key Features

🤖 AI-Powered EDI Generation

Claude AI generates realistic freight data and EDI 210 files. Select shipment type and quantity, get authentic company names, addresses, weights, and charges.

📄 EDI 210 Processing

Full ANSI X12 EDI 210 implementation. Parse existing files, generate new ones, convert to/from JSON, and auto-create invoice records.

💳 Payment Lifecycle

Secure payment processing with complete lifecycle management. Track status from pending through completed with audit trails.

📊 Invoice Management

Full CRUD operations for freight invoices. Track carrier, origin/destination, weights, charges, and payment status.

🚛 Carrier Management

Comprehensive carrier tracking with contact info, rates, and performance metrics. Real-time carrier data management.

🔍 Error Tracking

Custom middleware-based error logging. All errors captured to MongoDB with full context, timestamps, and stack traces.

🔐 Admin Panel

PIN-protected admin interface with multi-page navigation. View errors, manage data, and access system statistics.

📱 Mobile Responsive

Dedicated mobile CSS ensures full functionality on phones and tablets. Touch-optimized interfaces throughout.

Innovation: AI-Generated Freight Data

FPay leverages Claude AI to generate industry-realistic freight shipment data. Users select a shipment type (LTL, FTL, Refrigerated, Flatbed, Intermodal, Hazmat, Expedited, Parcel, White Glove, or Oversized/Heavy Haul) and quantity. Claude then generates authentic company names, addresses appropriate for the shipment type, realistic weights (e.g., lighter for parcel, heavier for oversized), appropriate freight charges, and complete EDI 210 files with proper segment structure. This dramatically accelerates testing and development while ensuring data quality.

EDI 210 Implementation

Full implementation of ANSI X12 EDI 210 (Motor Carrier Freight Details and Invoice) standard with:

EDI Structure

ISA/IEA: Interchange Control Headers (envelope)
GS/GE: Functional Group Headers
ST/SE: Transaction Set Headers (EDI 210 specific)
B3: Beginning Segment for Carrier's Invoice
N9: Reference Identification
G62: Date/Time
N1-N4 Loops: Name/Address segments for shipper, consignee, bill-to
LX: Assigned Number (line item loop)
L5: Description, Marks, and Numbers
L0: Line Item - Quantity and Weight
L1: Rate and Charges
L3: Total Weight and Charges

EDI Capabilities

Generation: Create compliant EDI 210 files from invoice data
Parsing: Convert EDI files back to structured JSON
Validation: Ensure all required segments present
Auto-Invoice: Create database invoices from parsed EDI
File Storage: Save generated EDI files to edi_files/ directory
Tracking: MongoDB documents track all EDI file metadata

Sample EDI 210 Segment

ISA*00*          *00*          *ZZ*SENDER123      *ZZ*RECEIVER456    *251115*1430*U*00401*000000001*0*P*~
GS*QM*SENDER123*RECEIVER456*20251115*1430*1*X*004010~
ST*210*0001~
B3*INVOICE123*SHIPMENT456*PP*50000*LB~
N9*BM*BOL123456~
G62*10*20251115~
N1*SF*ABC Logistics~
N3*123 Shipping Lane~
N4*Chicago*IL*60601~
N1*ST*XYZ Distribution~
N3*456 Receiving Blvd~
N4*Dallas*TX*75201~
LX*1~
L5*1*Freight Shipment~
L0*1*50000*LB~
L1*1*FR*5000.00~
L3*50000*LB*5000.00~
SE*16*0001~
GE*1*1~
IEA*1*000000001~

Technical Architecture

AI Integration

FPay uses Anthropic's Claude AI SDK (version 0.32.1) with these capabilities:

Structured prompt engineering for freight-specific data generation
10 shipment type templates (LTL, FTL, Reefer, Flatbed, Intermodal, Hazmat, Expedited, Parcel, White Glove, Oversized)
Realistic weight generation appropriate to shipment type
Industry-standard company names and addresses
Appropriate freight charge calculation based on weight and type
Complete EDI 210 file generation with proper segment structure
Batch generation support (multiple shipments in one request)

Error Tracking System

Custom middleware-based error instrumentation:

Automatic capture of all unhandled errors
MongoDB ErrorLog model with timestamp, error type, message, stack trace
Request context tracking (method, URL, headers, body)
Admin interface for viewing and analyzing errors
Instrumentation across all routes and critical operations
Production-grade observability for debugging

Security Implementation

Helmet.js: Security headers (CSP, HSTS, X-Frame-Options)
CORS: Configured cross-origin resource sharing
Compression: Response compression for performance
PIN Protection: Admin panel access control
Environment Variables: Secure credential management
MongoDB Encryption: Atlas encryption at rest

Project Structure

FPay/
├── server.js                    # Express server
├── models/
│   ├── Payment.js              # Payment lifecycle
│   ├── Invoice.js              # Invoice management
│   ├── Carrier.js              # Carrier tracking
│   ├── EDIDocument.js          # EDI metadata
│   └── ErrorLog.js             # Error tracking
├── routes/
│   ├── payments.js             # Payment APIs
│   ├── invoices.js             # Invoice APIs
│   ├── edi210.js               # EDI processing
│   ├── carriers.js             # Carrier APIs
│   └── errors.js               # Error retrieval
├── utils/
│   └── edi210Generator.js      # EDI class
├── middleware/
│   └── errorLogger.js          # Error tracking
├── public/
│   ├── index.html              # Dashboard
│   ├── admin.html              # Admin panel
│   ├── edi-generator.html      # AI interface
│   ├── errors.html             # Error viewer
│   └── mobile.css              # Responsive styles
├── edi_files/                  # Generated EDI
└── azure-pipelines.yml         # CI/CD

Supported Shipment Types

LTL (Less Than Truckload): Partial truckload shipments
FTL (Full Truckload): Dedicated full truck shipments
Refrigerated: Temperature-controlled freight
Flatbed: Open-top trailers for oversized items
Intermodal: Multi-modal transportation (truck/rail/ship)
Hazmat: Hazardous materials requiring special handling
Expedited: Time-critical rush shipments
Parcel: Small package delivery
White Glove: Premium handling and setup services
Oversized/Heavy Haul: Extra-large or overweight cargo

API Endpoints

Payment Management

POST /api/payments - Create new payment
GET /api/payments - List all payments
GET /api/payments/:id - Get payment details
PUT /api/payments/:id - Update payment
DELETE /api/payments/:id - Delete payment

EDI Processing

POST /api/edi210/generate - AI-generate EDI files
POST /api/edi210/parse - Parse EDI to JSON
GET /api/edi210/documents - List EDI documents

System

GET /health - Health check endpoint
GET /api/errors - Retrieve error logs
GET /api/stats - System statistics

Deployment

Azure Infrastructure

Hosting: Azure Web App with Node.js 24 runtime
Database: MongoDB Atlas (M0 Shared cluster)
CI/CD: Azure DevOps pipeline with automated deployment
Environment: Development (dev.freightpay.app)
SSL: Azure-managed SSL certificates

Build Pipeline

Commit triggers Azure DevOps pipeline
Install Node.js 24 and dependencies
Run tests and linting (if configured)
Package application with node_modules
Deploy to Azure Web App
Restart application with new code

Documentation

FPay includes comprehensive inline documentation:

AZURE_SETUP.md: Complete Azure deployment guide with step-by-step instructions
EDI_210_README.md: EDI 210 standard documentation and implementation details
CLAUDE_AI_EDI_README.md: AI generation guide with examples and best practices
ERROR_TRACKING_GUIDE.md: Error logging system documentation
API Reference: Available at https://dev.freightpay.app/api

Future Enhancements

Additional EDI Standards: EDI 204 (Load Tender), EDI 214 (Shipment Status)
Payment Gateway Integration: Stripe/PayPal for actual payment processing
Advanced Analytics: Dashboard with payment trends, carrier performance metrics
Mobile Apps: Native iOS/Android apps with Capacitor
Multi-Tenant: Support for multiple freight companies
Audit Trails: Complete audit logging for compliance
Automated Reconciliation: Match payments to invoices automatically
Rate Shopping: Compare carrier rates and select best option

Lessons Learned

AI Prompt Engineering Matters: Specific prompts for each shipment type produce much better results than generic prompts
EDI Standards are Complex: ANSI X12 has very specific segment ordering and delimiter requirements. Thorough testing essential.
Error Tracking from Day One: Adding error instrumentation early paid dividends in debugging production issues
Realistic Test Data: AI-generated data is far superior to hardcoded test data for finding edge cases
Mobile-First CSS: Dedicated mobile styles are better than trying to make desktop CSS responsive

← Back to Current Projects