Middleware (BURQ)

Every agribusiness sits at the centre of a web of connected systems. The bank sending payment confirmations. The weighbridge sending tonnage readings. The weather service sending forecasts. The packing-line sensors reading temperatures every second. The buyer EDI portal sending orders. The mobile-money provider sending settlement confirmations. The tax authority requiring electronic filings. Each of these is a system in its own right, with its own protocols, its own data formats, its own quirks, its own reliability.

BURQ is AgriERP’s middleware orchestration layer, the engine that handles all of this without polluting the rest of the system with one-off integrations. It is the layer that converts the messy outside world of dozens of partner systems into a clean, structured, predictable flow of data into and out of AgriERP. This document describes what BURQ is, what it does, and why having it as a dedicated layer matters.

1. Why a dedicated middleware layer

The problem with point-to-point integrations

The easy way to integrate two systems is to write a direct connection between them. AgriERP’s invoice module calls the bank’s payment API; the weighbridge writes directly to AgriERP’s inventory database. Each integration is simple in isolation. But as the number of connected systems grows, the easy way produces a tangle: ten systems can mean up to forty-five point-to-point integrations, each with its own connection logic, error handling, retry policy, and authentication scheme. When one system changes, multiple integrations break. When the business adds a new system, everything has to know about it. The result is fragile, slow to extend, and expensive to maintain.

What changes with a middleware layer

Capability	What it means in practice
One connection per system	Each external system connects once, to BURQ. AgriERP itself does not know about the external system directly; it knows about BURQ. New external systems are added by configuring BURQ, not by modifying the core ERP.
Standardised inside, varied outside	Inside AgriERP, every integration looks the same: structured data on a defined channel. Outside, BURQ deals with the real-world variety of formats, protocols, authentication, and reliability.
Decoupled change	When a buyer changes their EDI format, only BURQ’s connector for that buyer needs to change. The rest of the system is unaware. Similarly, when AgriERP upgrades a module, BURQ’s translation layer handles the change without external systems noticing.
Centralised reliability	All retry, dead-letter, replay, and failure-handling logic lives in BURQ. The business has one place to look when something is going wrong with an integration, not dozens.
Observable end-to-end	Every message flowing in or out passes through BURQ, where it can be logged, monitored, and traced. The integration health of the business is visible in one dashboard.

2. What BURQ does

API integrations

• Outbound calls: AgriERP needs to send data to external systems (banks, payment providers, weather services, government tax portals, buyer EDI systems). BURQ handles every outbound API call: authentication, retries, error handling, response parsing.
• Inbound calls: external systems need to send data into AgriERP (buyer orders, payment confirmations, sensor readings, market data, regulatory updates). BURQ exposes the inbound APIs, validates the data, and routes it to the right destination inside AgriERP.
• Authentication management: every external system has its own authentication: API keys, OAuth tokens, certificates, signed requests. BURQ manages the credentials securely and refreshes them when needed; the rest of AgriERP does not handle credentials directly.
• Rate limiting and throttling: many external systems have rate limits (how many requests per minute the business can make). BURQ tracks the limits, throttles requests to stay within them, and queues excess requests rather than failing.
• API versioning: external systems update their APIs; BURQ handles version-pinning, backward compatibility, and migration when needed, so the rest of AgriERP does not have to track API version churn.

Data transformation

Capability	What it means in practice
Format conversion	Each external system speaks its own format: JSON, XML, EDI X12 or EDIFACT, fixed-width text files, CSV, custom proprietary formats. BURQ converts to and from AgriERP’s internal structured format.
Schema mapping	External field names (“PO_NUMBER,” “orderId,” “DocNum”) are mapped to AgriERP’s standard field names. Mappings live in BURQ; AgriERP only ever sees its standard names.
Code and reference translation	External systems use their own codes (their product codes, their location codes, their unit codes). BURQ translates between external codes and AgriERP’s internal codes. “Our SKU 18-KG-MANDARIN” is also “the buyer’s product code 4827393” and “the customs HS code 0805.21.”
Validation	Incoming data is validated against expected schemas, value ranges, and business rules before it enters AgriERP. Bad data is rejected at the integration boundary, not after it has corrupted the operational records.
Enrichment	Where incoming data is incomplete, BURQ can enrich it with reference data from AgriERP or other sources before passing it on. A bank payment that lists only an account number can be enriched with the customer name before the matching workflow runs.
Unit and currency conversion	Where external data uses different units or currencies than AgriERP, BURQ handles conversion (with exchange rates fetched from configured sources).

Orchestration of multi-step flows

Most real integrations are not a single API call; they are a sequence of steps that have to happen in the right order, with the right error handling. BURQ orchestrates these flows, so the business does not have to.

• Sequential flows: step A must finish before step B starts. A grower settlement run: calculate amounts → generate payment file → submit to bank → receive confirmation → update settlement records → notify growers. Each step depends on the prior one.
• Parallel flows: where steps can run in parallel, BURQ runs them in parallel for speed. A buyer order arriving may simultaneously trigger inventory reservation, credit check, and shipping pre-arrangement. Each completes; the overall response goes back to the buyer once all are done.
• Conditional flows: where the next step depends on the prior step’s outcome, BURQ routes accordingly. A three-way match flow: if matched, send to payment; if not matched within tolerance, route to exception review; if matched within tolerance, post directly.
• Compensation flows: where a multi-step flow fails partway through, BURQ handles the compensating actions to roll back partial state. A grower payment that fails after the GL entry has posted needs the GL entry reversed; BURQ orchestrates the rollback.
• Long-running flows: where a flow spans hours or days (a customs clearance, a multi-day shipment), BURQ tracks the state, resumes after pauses, and times out cleanly if something gets stuck.

3. Operational concerns BURQ handles

Reliability

• Retries: where an external system is temporarily unavailable (network blip, brief downtime), BURQ retries automatically with appropriate backoff. The rest of AgriERP does not see the transient failure.
• Dead-letter handling: where retries are exhausted and a message cannot be delivered, it lands in a dead-letter queue for human investigation, not lost or silently retried forever.
• Idempotency: BURQ ensures that retried operations do not double-process. The same payment instruction submitted twice (because the first response was lost) results in one payment, not two.
• Circuit breaking: where an external system is clearly down (multiple consecutive failures), BURQ stops hitting it for a configured period and routes to fallbacks. Prevents a failing partner from cascading failures into AgriERP.
• Replay: where messages were processed incorrectly (a bug in transformation, a misconfiguration), BURQ can replay them from history once the issue is fixed. Recovery without manual data restoration.

Monitoring and observability

Capability	What it means in practice
Integration health dashboard	Real-time view of every active integration: message volume, success rate, latency, error rate. One place to see whether the system’s connections are running smoothly.
Per-integration alerts	When an integration’s error rate, latency, or queue depth crosses a threshold, the right people are alerted. Issues surface before they become customer-visible problems.
Message tracing	Any message flowing through BURQ can be traced: where it came from, what transformations were applied, where it went, what response came back. Useful for debugging and audit.
Audit trail	Every message and every action BURQ takes is logged. The audit trail is queryable for compliance, dispute resolution, and forensic analysis.
SLA tracking	Where integrations have agreed service levels (banking integrations, buyer EDI), BURQ tracks performance against those SLAs and reports compliance.
Historical analytics	Long-term integration patterns: which integrations are busiest, which are slowest, which have the most exceptions. Useful for capacity planning and partner-relationship management.

Security

• Credential vault: API keys, tokens, and certificates for every external system are stored in a managed key vault. They are not in code or configuration files.
• Transport encryption: every connection in and out uses TLS encryption. No plain-text data crosses the integration boundary.
• Message-level signing: for high-value flows (bank payments, large customer orders), messages are signed or hashed for non-repudiation. The business can prove the message was sent or received exactly as captured.
• IP allowlisting: where external partners require it, AgriERP’s outbound traffic comes from defined IP ranges; inbound traffic is restricted to defined source ranges.
• Data masking: in logs and monitoring, sensitive fields (bank account numbers, taxpayer IDs, personal details) are masked. Visible in audit when authorised; masked in routine operational views.
• Audit segregation: BURQ logs are immutable and access-controlled separately from operational data, so even an attacker with operational access cannot rewrite integration history.

4. Extending BURQ

Adding a new integration

When the business wants to connect a new external system, the work happens in BURQ, not in AgriERP. The integration team configures the connector, the data transformation, and the orchestration. The rest of AgriERP is unchanged; the new system’s data simply starts arriving.

• Connector configuration: the connection to the external system: endpoint, authentication method, format, version. Most common connector types ship out of the box (REST, SOAP, EDI X12, EDIFACT, SFTP, message queues).
• Mapping definition: the field-by-field mapping between the external system’s format and AgriERP’s structured data. Common mappings are templated; bespoke mappings are configured.
• Orchestration design: the flow of steps for the integration: when it triggers, what happens, what the success criteria are, what the failure handling is.
• Testing in a sandbox: new integrations are tested in a sandbox environment against the partner’s test endpoints, with synthetic data, before going live.
• Phased rollout: live rollout is typically phased: a small set of transactions or a small share of traffic, with full monitoring, before the integration takes the full load.

Custom connectors and partner extensions

• Out-of-the-box connectors: BURQ ships with connectors for common categories: major banks, payment gateways, weather services, market-data providers, customs systems, common buyer EDI formats.
• Custom connectors: for unusual or business-specific external systems, custom connectors are built and registered with BURQ. Once registered, they behave like the standard connectors.
• Partner-specific extensions: where a specific partner needs nonstandard handling (a quirky format, a legacy protocol, special compliance requirements), the extension lives in BURQ. The peculiarity is isolated to its connector.
• Versioned and rollback-able: integration configurations are versioned, so changes can be rolled back if they cause problems. New versions go through testing before activation.

Why BURQ is named as a separate thingMany ERP systems handle integrations “somewhere in the platform.” The result is that integrations end up as a series of bolt-on tools, each with its own administration, each with its own monitoring, none of them with a clear owner. When something breaks, finding the right tool takes longer than fixing the problem.BURQ is named as a separate component because integration is a separate problem with its own discipline. The team that runs integrations runs BURQ. The dashboard that shows integration health is BURQ’s dashboard. The configurations that define integrations live in BURQ’s repository. Naming it makes it manageable.

In summary

BURQ is the middleware orchestration layer that handles every API integration, every data transformation, every multi-step flow, and every operational concern of running integrations at scale. It turns the messy outside world of dozens of partner systems into a clean, structured flow of data into and out of AgriERP. Reliability, monitoring, security, and extensibility are all platform concerns BURQ handles, not problems each integration solves separately.

Without BURQ, every external system would push its complexity into the core ERP, creating fragile, hard-to-maintain integration code. With BURQ, the core ERP stays clean and focused on the agricultural business it runs, while the integration layer absorbs the complexity of the outside world.