merchmix-arro-rust-be
currentARRO is a Rust workspace providing Merchmix’s merchandise allocation, replenishment, store clustering, size mapping, analytics, and related operational APIs. The main `arro-api` binary exposes Axum HTTP and MCP interfaces, uses PostgreSQL and Redis for application state and caching, and integrates with external AI, synchronisation, customisation, and ERP connector services. Shared allocation, clustering, and refill calculation engines are implemented in `arro-core` and can also be compiled to WebAssembly for browser-side use. A separate `arro-worker` process runs background allocation-sync and store-metrics jobs.
Business summary
This service helps retailers decide how much stock each store should receive, replenish stores, and manage the rules behind those decisions. It supports purchase-order allocation, store grouping, size mapping, inventory and sales analysis, replenishment runs, and operational transfers. Retail users can work through APIs or connected Merchmix tools, while background workers keep allocation and store metrics up to date.
Capabilities
12Plans and manages how purchase-order stock is distributed across stores and other destinations for a product.
The API exposes purchase-order and SKU allocation reads, allocation edits, summaries, mapping coverage, completion, revert, cache clearing, bulk plan creation, and bulk revenue operations. `arro-core::allocation` contains the allocation operation, reconciliation, rounding, validation, waterfall, and rollup engines; allocation v2 persists append-style operations and supports replay and commit flows.
Creates and executes refill plans to restore stock at stores based on available inventory, demand, and configured guardrails.
The v2 refill API supports refill periods, SKU and style-matrix reads, run creation, daily execution, grid retrieval, preview, commit, and distribution-centre guardrails. `arro-core::refill` provides engine, routing, scaling, hashing, and guardrail logic; the worker also contains allocation-sync processing.
Groups stores with similar characteristics so allocation and planning rules can be applied appropriately.
Cluster handlers and services support cluster CRUD, automatic clustering, previews, projections, health and drift analysis, outliers, threshold suggestions, store movement, cell-store views, and resolving store assignments. `arro-core::clustering` implements k-means and robust threshold computation.
Maintains mappings between product size labels and consolidated size groups used for planning and reporting.
The consolidated size-mapping API supports list, detail, bulk update, import, export, refresh, validation, summaries, streaming synchronisation, and synchronisation to size mappings. Dedicated services cover import, suggestions, validation, normalisation, reporting, templates, and size strategies.
Uses size relationships and historical signals to support more appropriate size-level allocation and replenishment decisions.
The repository contains size-curve blending, confidence, fallback, generation, extraction, strategy resolution, validation, backtesting, templates, and size-reporting services. These services are connected to allocation and refill domain types, although the supplied endpoint inventory does not establish the complete public route surface for every service.
Provides current and derived views of stock, including purchase-order stock, total stock-on-hand, in-transit stock, and inventory snapshots.
Handlers and services include inventory, inventory snapshots, DC inventory, in-transit stock, store caches, purchase-order reads, bulk-refill stock totals, and ERP connector contracts for pulling inventory snapshots.
Helps retail teams identify coverage gaps, compare stores, and rank styles using sales and store performance data.
Analytics routes expose coverage gaps overall and by store, peer benchmarking, and style leaderboards. `arro-bigquery` contains analytics, store, purchase-order, and size-sales repositories; store-metrics refresh and worker jobs support derived metrics.
Maintains store or product buying grades that can influence merchandise planning decisions.
The API exposes buy-grade listing, retrieval, and store-related reads, backed by `buy_grades_service` and platform/domain buy-grade types.
Coordinates stock transfers between stores and can route transfer documents to a tenant’s ERP.
A store-transfer service and MCP tools are present, and the ERP connector protobuf defines idempotent `PushStoreTransfer`, job-status lookup, held-order listing, and selected hold-release operations. The supplied HTTP route scan does not show the complete store-transfer route set, so public REST exposure is not fully established.
Sends supported inventory transfer or purchase-order actions to a tenant’s configured ERP and tracks the result.
A vendored gRPC `ErpConnector` contract defines transfer push, purchase-order push, inventory pull, idempotent job status, held-order listing, and selected hold release. Tenant configuration selects ERP type and connector routing; comments mark purchase-order push, inventory pull, and some hold operations as unimplemented for relevant adapters.
Refreshes derived store metrics and queues or commits planning changes so operational data stays current.
Internal routes expose refresh status and store-metrics refresh. The platform includes commit queue types and run-queue services, while `arro-worker` runs allocation-sync and store-metrics processors. A one-shot worker mode is supported by the `arro-api` binary command line.
Allows connected AI agents to query and operate supported Merchmix planning workflows through structured tools.
The API exposes `/.well-known/mcp-service` and a streamable HTTP MCP service using `rmcp`. MCP tools cover stores, clusters, buy grades, size templates, size mappings, allocation v1 and v2, and store transfers. MCP tenant resolution requires a `client_id` that exists in the loaded tenant configuration.
Workflows
5A planner reviews open purchase orders, edits or evaluates SKU allocation, and completes or reverts the allocation.
- 1.List open purchase orders or bulk-refill purchase orders.
- 2.Retrieve purchase-order detail and SKU allocation state.
- 3.Review allocation summary and size-mapping coverage.
- 4.Update, complete, revert, or clear cached allocation state.
- 5.Optionally create allocation plans in bulk and commit downstream planning changes.
A planner or scheduled process builds a refill run, previews its result, and commits approved replenishment quantities.
- 1.Configure or select a refill period and DC guardrails.
- 2.Create a refill run for a purchase order, style, cluster, or period.
- 3.Retrieve the refill grid or style replenishment matrix.
- 4.Preview the run and inspect calculated quantities.
- 5.Commit the approved run or execute the daily run path.
Stores are analysed and assigned to clusters that can be used by allocation and refill calculations.
- 1.Inspect cluster health, drift, outliers, and current store assignments.
- 2.Preview or calculate automatic clustering and threshold suggestions.
- 3.Move stores or resolve assignments.
- 4.Use the resulting cluster or projection in allocation or refill runs.
Product size labels are validated, consolidated, and synchronised for downstream planning and reporting.
- 1.Import or inspect size mappings.
- 2.Validate mappings and review suggestions or summaries.
- 3.Apply bulk updates or synchronise to the size-mapping representation.
- 4.Refresh or stream synchronisation data and export the result.
A supported transfer is submitted to the configured tenant ERP with retry-safe job tracking.
- 1.Resolve the tenant and configured ERP connector route.
- 2.Submit the store-transfer request with an idempotency key.
- 3.Read the returned job result and, if needed, query status using the same key.
- 4.Treat each returned item’s success or error as authoritative for hold-release style operations.
Architecture
A Cargo workspace separates shared domain types, pure planning engines, data repositories, HTTP/API orchestration, projections, worker jobs, and WebAssembly bindings. `arro-api` constructs shared and tenant-specific PostgreSQL pools, optional Redis and secondary data pools, outbound service clients, and Axum routers. Request tenant identity is resolved against configured tenant state; MCP calls reproduce this check because they bypass the normal REST middleware.
Interfaces
10| Kind | Identifier | Description |
|---|---|---|
| http | REST `/api/v1/allocation/*` | Purchase-order and SKU allocation reads, edits, completion, revert, summaries, mapping coverage, cache control, bulk plan creation, and bulk revenue operations. |
| http | REST `/api/v2/refill/*` | Refill periods, SKU/style matrices, refill runs, previews, grids, commits, daily execution, and DC guardrails. |
| http | REST `/api/v1/clusters/*` | Cluster creation and management, auto-clustering, projections, health, drift, outliers, previews, thresholds, and store assignments. |
| http | REST `/api/v1/consolidated-size-mappings/*` | Consolidated size-mapping CRUD, import/export, validation, refresh, summaries, and synchronisation. |
| http | REST `/api/v1/analytics/*` | Coverage gaps, store peer benchmarks, and style leaderboards. |
| http | REST `/api/v1/buy-grades*` | Buy-grade and store buy-grade reads and management. |
| http | REST `/api/v1/internal/*` | Internal refresh status and store-metrics refresh operations. |
| http | MCP `/.well-known/mcp-service` and streamable HTTP MCP endpoint | Agent-facing discovery and structured tools for stores, clusters, buy grades, size templates, size mappings, allocation, and store transfers. |
| grpc | `merchmix.erp.v1.ErpConnector` | Outbound tenant/ERP connector contract for transfer pushes, purchase-order pushes, inventory pulls, job status, held-order listing, and selected hold release. |
| cli | `arro-api run-worker` and `cargo run -p arro-worker` | Runs background processing, including a one-shot API run-queue worker mode and the standalone worker binary. |
Data
11| Entity | Ownership | Description |
|---|---|---|
| Tenant configuration and tenant state | owns | Tenant identifiers, tenant database connection configuration, ERP routing settings, and sales-tax divisor used by API and worker processes. |
| Allocation plans and allocation operations | owns | Purchase-order/SKU allocation state, append-style allocation operations, actors, sequences, summaries, and commit/replay data. |
| Purchase orders | reads | Open purchase orders and purchase-order detail used by allocation and refill workflows. |
| Inventory snapshots and stock-on-hand | owns | Inventory snapshot records, total stock, DC inventory, and in-transit stock used for allocation and replenishment. |
| Store attributes and store hierarchy | owns | Store metadata, active status, DC flags, climate and hierarchy information, and store/DC relationships. |
| Store clusters and assignments | owns | Clusters, store membership, overrides, health/drift information, projections, and committed snapshots. |
| Store metrics and analytics facts | writes | Derived store metrics, coverage-gap inputs, peer benchmarks, style performance, and size-sales reporting data. |
| Size mappings and consolidated size mappings | owns | Product size labels, consolidated groups, mapping names, validation results, and synchronisation data. |
| Buy grades | owns | Buy-grade records and store associations used by buying and planning workflows. |
| Refill periods, runs, grids, and guardrails | owns | Configured refill periods, replenishment runs, calculated grids, daily execution state, and DC guardrails. |
| ERP job results | writes | Idempotency keys and submitted connector job outcomes used to avoid duplicate downstream ERP actions and query status. |
Dependencies
10| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL | database | reads | critical |
| Redis | database | uses | required |
| Secondary analytics data store | database | reads | supporting |
| Merchmix Basics service | internal service | calls | supporting |
| ARRO AI service | internal service | calls | supporting |
| Merchmix synchronisation service | internal service | calls | required |
| Customisation service | internal service | calls | supporting |
| ERP connector | internal service | calls | required |
| Arrow IPC | library | uses | supporting |
| MCP Rust SDK | library | uses | supporting |
Technology
Limitations
6- —The supplied HTTP endpoint scan is incomplete relative to the handler modules; several registered handler modules, including store transfers, inventory, stores, size strategies, and platform operations, are not fully represented in the listed routes.
- —No runtime deployment health, route authentication policy, request schemas, or production readiness evidence was supplied beyond source structure and manifests.
- —The repository contains comments identifying some ERP connector RPCs as unimplemented for relevant adapters; do not assume purchase-order push, inventory pull, or all held-order operations work for every tenant.
- —The evidence does not establish whether all listed capabilities are enabled for every tenant or whether all APIs are externally user-facing.
- —No screen or frontend route evidence was provided; this repository should be treated as a backend/API and shared-engine repository.
- —The exact MCP endpoint path beyond discovery is not included in the supplied HTTP route list.
Agent instructions
Use this repository for allocation, replenishment, store clustering, size planning, inventory visibility, analytics, and related Merchmix operational workflows. Resolve tenant context before taking action and distinguish previews and reads from commits or ERP submissions.
- →For tenant-scoped operations, require a valid `client_id` matching the loaded tenant configuration; do not infer or silently default a tenant.
- →Prefer preview, summary, validation, health, and mapping-coverage operations before write, commit, revert, or ERP execution operations.
- →Treat allocation and refill calculations as shared domain logic; avoid duplicating business rules outside `arro-core` when modifying behaviour.
- →When using allocation v2, preserve append/replay semantics and validate operation payloads before persistence.
- →For ERP actions, always provide and preserve an idempotency key, inspect the returned job status, and treat per-item success/error fields as authoritative.
- →Do not assume an ERP RPC is implemented for every configured ERP type; verify adapter support before invoking it.
- →Use internal refresh and worker operations cautiously because they can rebuild derived metrics or process queued work.
- →Never read, print, or commit secret values from tenant configuration, environment files, connector credentials, or deployment manifests.