N8N System Manual: MDL Ops Intelligence (v2)

This manual provides technical documentation for the n8n v2 infrastructure and workflows hosted within the MDL Ops Engine.

1. System Architecture

The system is built on a modular Docker-based architecture for high reliability and AI-driven processing.

1.1 Docker Services

• n8n-v2: The core automation engine (n8nio/n8n).
• n8n-db-v2: PostgreSQL 16 database for workflow persistence.
• excel-api: A custom Flask API using Aspose/Pandas for high-fidelity Excel-to-Image and Excel-to-JSON conversion.
• python-runner-v2: Dedicated task runner for executing complex Python scripts within workflows.
• cloudflared: Secure tunnel connector that exposes n8n to the public internet without opening firewall ports.

1.2 Connectivity & Public Access

• Domain: https://automate.mdlcommunications.com
• Tunneling: Powered by Cloudflare Zero Trust. The system uses a locally configured tunnel (n8n-mdl-v2) with a dedicated config.yml for precise routing.
• Webhooks: Publicly accessible via https://automate.mdlcommunications.com/webhook/.
• Local Files: Mapped to /app (project root) and ./local-files (n8n specific).

2. The "FINAL MASTER" Workflow

The system uses a unified master workflow that handles all quote intake and analysis.

2.1 Intake & Routing

• Triggers:
• Outlook: Monitors mdlcommunications.com for emails with attachments.
• Manual Form: A public-facing form for direct file uploads.
• File Detection: Automatically differentiates between PDF (Supplier Quotes), XLSX (Sales Quotes), and Images.
• Quote ID Extraction: Uses AI to identify the Quote ID (e.g., ML2026xxxx) from filenames or document content if not explicitly provided.
• Duplicate & Freshness Filters (New: Feb 23, 2026):
• Freshness: Automatically skips documents older than 35 days to focus on current projects.
• Deduplication: Immediate QBO lookup for existing DocNumber to prevent redundant Bill creation.

2.2 Google Drive Synchronization

• Logic: Automatically creates or finds project folders in MDL-Ops-Work-In-Progress.
• Intake Management: Moves all incoming files to the correct project folder while maintaining version history.

2.3 AI Intelligence (Gemini 2.0 Flash)

• Task: Analyzes raw text from supplier quotes.
• Extracted Fields: subtotal, shipping, currency, supplier_reference, vendor_name.
• Training: Employs Few-Shot Prompting templates for high-accuracy extraction from vendors like Enensys, Sencore, Haivision, and Ateme.
• Supplier Discount Handling (Updated: Feb 2026):
• Automatically identifies and uses NET/DISCOUNTED prices as the actual cost
• Distinguishes between List Price (MSRP) and Net Price (negotiated cost)
• Detects discount keywords: "Net Total", "Your Price", "Final Price", "Subtotal after discount"
• Example: If Haivision shows List=$13,250 with 30% discount, the AI correctly uses $9,275 as cost
• Ensures accurate margin calculations for quotes with volume or partner discounts

2.4 Financial Audit & State Tracking

• Backbone Sync: Every intake event is logged in the Google Sheet "Backbone" (WORK_ITEMS tab) to track status (Intake -> Analyzed -> Audited).
• Audit Logic: Compares AI-extracted costs against Sales Excel data.
• Audit Log: Detailed financial results (Margin, Profit, Discrepancies) are logged to the "Quote Audit Log" sheet.
• Shipping Bill Ingestion (TotalShip/NoviShip):
• Specialized workflow for processing carrier invoices.
• Monitors "Invoices Received" folder for "totalship" or "noviship" keywords.
• Automatically identifies the PDF invoice from multi-attachment emails using native n8n binary expressions.
• Pushes bill data to QBO and triggers weight-based cost splits.
• Includes PO Resolution fallback (cross-referencing Email Subject if missing in document).

3. Maintenance and AI Training

The AI accuracy is maintained through a rigorous benchmarking process.

3.1 AI Training Pipeline

To add or improve vendor extraction: 1. Samples: Place new PDFs in n8n-docker/samples/{VENDOR}/. 2. Ground Truth: Run python n8n-docker/scripts/setup_ground_truth.py to create labeling templates. 3. Benchmarking: Run python n8n-docker/scripts/benchmark_ai.py to measure accuracy. 4. Prompt Tuning: Update the Gemini node in N8N with new "EXAMPLES" derived from the raw text of samples.

3.2 Excel API Maintenance

The excel-api service provides tools for: - Converting Sales Quotes to images for visual verification in Slack/Email. - Extracting specific cells for audit comparison.

4. Security & Access Control

Access to the n8n automation engine is strictly controlled via a dual-layer security model.

4.1 Layer 1: Network-Level SSO (Cloudflare)

Before reaching the application, users must authenticate via Microsoft Azure AD. - Scope: Access is restricted to @mdlcommunications.com email addresses. - Policy: Managed in the Cloudflare Zero Trust dashboard under "Access Applications". - Bot Protection: All search engine indexing is blocked via a global X-Robots-Tag: noindex policy and Cloudflare-level bot management.

4.2 Layer 2: Application-Level Auth (n8n)

Once past the Cloudflare wall, users must log in with their individual n8n service accounts.

5. Troubleshooting Reference