# merchmix-arro-rust-be

ARRO 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

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Inventory Allocation | Allocation | `production` | `write` | user_facing, agent_facing |
| Replenishment Planning | Planning | `production` | `execute` | user_facing, agent_facing, internal |
| Store Clustering | Planning | `production` | `write` | user_facing, agent_facing |
| Size Mapping Management | Planning | `production` | `write` | user_facing, agent_facing |
| Size Curve and Size Strategy Planning | Planning | `partial` | `execute` | user_facing, agent_facing, internal |
| Inventory and Stock Visibility | Inventory | `production` | `read` | user_facing, agent_facing |
| Merchandise Analytics | Reporting | `production` | `read` | user_facing, agent_facing, internal |
| Buy Grade Management | Planning | `production` | `write` | user_facing, agent_facing |
| Store Transfer Operations | Logistics | `partial` | `execute` | user_facing, agent_facing, internal |
| ERP Connector Integration | Logistics | `partial` | `execute` | internal, agent_facing |
| Operational Refresh and Commit Processing | Other | `production` | `execute` | internal |
| MCP Planning Assistance | Other | `beta` | `execute` | agent_facing |

**Inventory Allocation** — Plans and manages how purchase-order stock is distributed across stores and other destinations for a product.

**Replenishment Planning** — Creates and executes refill plans to restore stock at stores based on available inventory, demand, and configured guardrails.

**Store Clustering** — Groups stores with similar characteristics so allocation and planning rules can be applied appropriately.

**Size Mapping Management** — Maintains mappings between product size labels and consolidated size groups used for planning and reporting.

**Size Curve and Size Strategy Planning** — Uses size relationships and historical signals to support more appropriate size-level allocation and replenishment decisions.

**Inventory and Stock Visibility** — Provides current and derived views of stock, including purchase-order stock, total stock-on-hand, in-transit stock, and inventory snapshots.

**Merchandise Analytics** — Helps retail teams identify coverage gaps, compare stores, and rank styles using sales and store performance data.

**Buy Grade Management** — Maintains store or product buying grades that can influence merchandise planning decisions.

**Store Transfer Operations** — Coordinates stock transfers between stores and can route transfer documents to a tenant’s ERP.

**ERP Connector Integration** — Sends supported inventory transfer or purchase-order actions to a tenant’s configured ERP and tracks the result.

**Operational Refresh and Commit Processing** — Refreshes derived store metrics and queues or commits planning changes so operational data stays current.

**MCP Planning Assistance** — Allows connected AI agents to query and operate supported Merchmix planning workflows through structured tools.

## Workflows

**Purchase-order allocation** — A 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.

**Refill run execution** — 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.

**Cluster-driven planning** — 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.

**Size mapping synchronisation** — 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.

**ERP transfer submission** — 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.

**Components:** `arro-types`: shared common, domain, and platform data models., `arro-core`: pure allocation, clustering, refill, state, and tenant SQL logic., `arro-bigquery`: analytics, store, purchase-order, and size-sales repository layer; despite its name, its declared SQL dependency and `BQ_DATA` configuration indicate a secondary PostgreSQL data connection in this repository., `arro-projection`: Arrow IPC projection and codec support., `arro-api`: Axum REST API, MCP server, tenant state, handlers, services, migrations, outbound HTTP and gRPC clients., `arro-worker`: scheduled/background allocation-sync and store-metrics processors., `arro-wasm`: browser-compilable bindings for allocation, clustering, refill, replenishment, and size projection engines., PostgreSQL migrations: application tables and indexes for inventory snapshots, store attributes, size mappings, store/DC relationships, metrics, cluster overrides, and committed snapshots.

**Patterns:** Cargo workspace with shared crates and dependency injection through application state., Axum route modules with handler and service layers; some handlers perform SQL directly., Pure calculation engines in `arro-core`, reused by the API, worker, and WebAssembly build., Per-tenant database pools and tenant-aware routing configuration., Append/replay style persisted allocation operations for allocation v2., Redis-backed or cache-manager-assisted read/cache paths where configured., Background worker and run-queue processing for refresh and synchronisation., Streamable HTTP MCP server with structured tool definitions., gRPC protobuf contract for ERP integration.

## Interfaces

| 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

| 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

| 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

Rust 2021, Tokio, Axum 0.7, Serde and serde_json, SQLx and tokio-postgres, Refinery SQL migrations, Redis, Tonic/prost gRPC, rmcp MCP SDK, Arrow IPC, WebAssembly via wasm-bindgen, PostgreSQL, Docker, Azure Container Apps and Google Cloud Run deployment definitions

## Limitations

- 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.

## Source

| Field | Value |
|---|---|
| Repository | `merchmix-arro-rust-be` |
| Branch | `main` |
| Commit | `76267747339b` |
| Generated by | `gpt-5.6-luna` |

*Generated by the Merchmix Skills Platform from the current codebase.*