merchmix-option-plan-be

current

This repository is the backend for Merchmix Option Planning. It provides HTTP, gRPC, and MCP interfaces to create and manage option plan masters and plans, capture approvals and workspace configuration, assign styles and suppliers, generate recommendation and sync statistics views, preview and push plans into range planning, and expose option-plan data to other internal services. It persists its own option-planning data in PostgreSQL, uses Redis as an optional cache, and integrates with assortment, WSSI, prediction, notification, telemetry, OpenAI, and Google Cloud services.

master·fa95956299d9·generated by gpt-5.4·9/4/2026, 10:43:30 AM View as Markdown

Business summary

This service helps retailers build and manage option plans: the working plans that decide what styles, suppliers, and quantities should be bought for a season. Teams can set targets, review recommendations, approve plans, capture working snapshots, and push approved outcomes into range planning. It also connects to other Merchmix services so planners can bring in supporting data, generate planning notes, and share plan information across the platform.

Capabilities

Option PlanningproductionwritePlanninguser facingagent facing97%

Create, update, view, and delete option plans and their parent planning workspaces.

Exposes REST endpoints for /option-plan-masters, /option-plan-masters/:id_or_slug, /option-plans, and /option-plans/:id with create/read/update/delete handlers in src/http/option_plan_routes.rs wired from src/http/mod.rs. Repository contains dedicated models and DB modules for option plans and option plan settings.

Option Plan Target SettingproductionwritePlanninguser facingagent facing92%

Maintain plan-level grid targets and workspace column preferences used by planners during option planning.

Supports PATCH /option-plan-masters/:id_or_slug/grid-targets and PUT /option-plan-masters/:id_or_slug/workspace-columns, plus global settings via GET/PUT /option-plan-settings. Migrations include option_plan_settings, workspace_columns, plan_windows, and auto grid generation support.

Option Plan ApprovalproductionwritePlanninguser facingagent facinginternal93%

Record and retrieve approval status for option plans so teams can track whether a plan is ready to move forward.

Implements GET/POST /option-plan-masters/:id_or_slug/approval through approval routes and has domain logic under src/domain/approval. Approval transitions also trigger notification publishing via the notify module.

Style AssignmentproductionwriteProductsuser facingagent facinginternal95%

Assign styles to an option plan, initialize assignments, and perform bulk assignment updates for planning work.

Exposes GET/PUT style assignment paths under /option-plan-masters/:id_or_slug/style-assignments, /bulk, and /initialize. Also exposes gRPC OptionPlanStyleService.GetLatestStyleAssignments to other services, enriching assignments from synced style summary tables.

Supplier AssignmentproductionwriteSuppliersuser facingagent facing84%

Manage supplier assignments and supplier assignment options within an option plan.

Routes include /option-plan-masters/:id/supplier-assignments and /option-plan-masters/:id/supplier-assignments/options. Schema support is visible in migrations such as style_assignments, add_subcategory_to_assignments, and style_supplier_override.

Range Plan Preview and PushproductionexecutePlanninguser facingagent facinginternal94%

Preview how an option plan will map into range planning, then push selected plan content into the range board and track job status.

Implements range-plan preview endpoints under /option-plan-masters/:id/range-plan-previews and commit, plus push endpoints /option-plan-masters/:id_or_slug/push-to-range-board and /status/:job_id. Migrations create range_plan_push_queue, range_plan_previews, and push_job tables. The service also calls the Assortment gRPC service for range-plan-side creation operations.

Planning RecommendationsproductionreadForecastinguser facingagent facing90%

Provide recommendation outputs to help planners decide what action to take on styles or options.

Exposes GET /option-plan-masters/:id_or_slug/recommendations and POST /predict-recommendations. Contains recommendation domain code in src/domain/reco_engine and an external predict client in src/predict that calls predict.backend.merchmix.co and caches responses via Redis.

Sync Statistics and WSSI SupportproductionreadReportinguser facingagent facinginternal90%

Show planning statistics and WSSI-derived supporting values used during option planning and budget context.

Exposes /option-plan-masters/:id_or_slug/sync-stats and contains WSSI and budget client modules that call the WSSI gRPC service for GenerateWssi, GetBudgetExportValues, and GetBudgetExportBreakdown. Sync-related migrations include sync_stats_fallback, sync_stats_months, and update_sync_filters.

AI Planning Notes GenerationbetaexecutePlanninguser facingagent facing87%

Generate concise planning notes for an option plan using AI based on plan data.

Exposes POST /option-plan/write-with-ai/:slug and includes src/openai/mod.rs, which calls OpenAI chat completions using a configured model and a retail-planning prompt focused on approval notes, architecture mix, and targets.

Option Plan Data Access for Internal ServicesproductionreadOtherinternalagent facing95%

Allow other internal systems to list option plans, fetch option plan details, and retrieve latest style assignments.

Provides gRPC methods ListOptionPlans and GetOptionPlan in CoreOptionPlanService, plus GetLatestStyleAssignments in OptionPlanStyleService. Also serves MCP over /.well-known/mcp-service for tool-based agent access to option-plan operations.

Approval NotificationsproductionexecuteOtherinternal86%

Send user notifications when option plan approval status changes.

Uses notify.v1 NotificationService protobuf client code and a fire-and-forget dispatcher in src/notify to publish approval-related notifications to notification.merchmix.co without blocking the main transaction.

Workflows

Create and manage an option plan

Planner creates a plan workspace, adds plan records, and maintains configuration used during planning.

1.Create an option plan master via POST /option-plan-masters
2.Create one or more option plans via POST /option-plans
3.Retrieve and edit plans with GET/PUT /option-plans/:id
4.Adjust grid targets and workspace columns on the master
5.Read settings and formulas to support planning views

Assign styles and suppliers to a plan

Planner initializes or updates the product and supplier choices attached to the option plan.

1.Initialize style assignments for a master
2.Fetch current style assignments
3.Apply bulk or individual style assignment updates
4.Manage supplier assignments and available supplier assignment options
5.Optionally retrieve latest assignments through gRPC from another internal service

Review, approve, and notify

Planning team reviews a plan, records approval state, and emits notifications.

1.Fetch recommendation outputs for the plan
2.Read approval state via GET /option-plan-masters/:id_or_slug/approval
3.Submit approval action via POST /option-plan-masters/:id_or_slug/approval
4.Emit approval notification asynchronously to notify-service
5.Optionally generate AI-written notes for the plan

Preview and push to range planning

Planner previews a downstream range plan impact and then pushes approved content into range planning.

1.Create a range-plan preview for an option plan master
2.Inspect preview details
3.Commit the preview if acceptable
4.Trigger push to range board
5.Poll push job status until complete

Fetch planning support data

The service gathers recommendation, WSSI, budget, and sync data to enrich planning decisions.

1.Call prediction backend for option-plan analysis data
2.Cache or reuse responses through Redis when available
3.Call WSSI gRPC service for generated WSSI or budget exports
4.Store gRPC call logs in PostgreSQL
5.Return aggregated support data to the requesting screen or tool

Architecture

Rust service built on Axum for HTTP APIs, Tonic for gRPC clients and servers, SQLx for PostgreSQL persistence, optional Redis caching, and RMCP streamable HTTP for agent tooling. It is a multi-interface backend with its own database schema, plus background tasks for sync index maintenance, telemetry, and notification dispatch.

Components

HTTP API router under src/http with domain-specific route modulesgRPC server under src/grpc_server exposing option-plan and style-assignment contractsgRPC clients for assortment, WSSI, and notification servicesMCP server under src/mcp exposing tool-based access over streamable HTTPPostgreSQL access layer under src/db and migrations/Optional Redis cache layer under src/cache/redisExternal integration modules for OpenAI, predict backend, GCP credential loading, telemetry, and notify dispatch

Patterns

Monolithic service with multiple protocolsPostgreSQL-first persistence with SQL migrationsClient-id based multi-tenancySynchronous request handlers plus asynchronous background workersBest-effort external side effects for telemetry and notificationsGateway/integration pattern to internal gRPC services

Interfaces

Kind	Identifier	Description
http	`/healthz, /readyz, /whoami`	Operational and identity endpoints for liveness, readiness, and caller context.
http	`/option-plan-masters, /option-plan-masters/:id_or_slug, /option-plans, /option-plans/:id`	Primary REST API for option plan masters and plans.
http	`/option-plan-masters/:id_or_slug/approval`	Approval read/write API for option plan workflows.
http	`/option-plan-masters/:id_or_slug/style-assignments and related bulk/initialize routes`	REST interface for style assignment management.
http	`/option-plan-masters/:id/supplier-assignments and /options`	REST interface for supplier assignment management.
http	`/option-plan-masters/:id/range-plan-previews and commit routes`	REST interface for generating and committing range plan previews.
http	`/option-plan-masters/:id_or_slug/push-to-range-board and status/:job_id`	REST interface for pushing option plans into the range board and checking async status.
http	`/predict-recommendations, /metric-formulas, /option-plan-settings, /option-plan/write-with-ai/:slug, /option-plan-masters/:id_or_slug/sync-stats`	Supporting REST APIs for recommendations, formulas, settings, AI notes, and sync statistics.
grpc	`option_plan.OptionPlanStyleService/GetLatestStyleAssignments`	Internal gRPC API returning latest style assignments by tenant.
grpc	`forge.core.v1.CoreOptionPlanService/ListOptionPlans, GetOptionPlan`	Internal gRPC API exposing option plan summaries and detail to other Merchmix services.
other	`/.well-known/mcp-service`	RMCP streamable HTTP endpoint exposing tool-based agent operations over option-plan workflows.

Screens

Route	Name	Purpose
`/option-plan-masters`	Option Plan Masters	List and create option planning workspaces.
`/option-plan-masters/:id_or_slug`	Option Plan Master Detail	View or delete a specific option planning workspace.
`/option-plans`	Option Plans	List and create individual option plan records.
`/option-plans/:id`	Option Plan Detail	View, update, or delete a specific option plan.
`/option-plan-masters/:id_or_slug/grid-targets`	Grid Targets	Update target values used in planning grids.
`/option-plan-masters/:id_or_slug/workspace-columns`	Workspace Columns	Persist workspace column configuration.
`/option-plan-masters/:id_or_slug/approval`	Approval	View or submit approval status.
`/option-plan-masters/:id_or_slug/recommendations`	Recommendations	View recommendation outputs for a plan.
`/option-plan-masters/:id_or_slug/style-assignments`	Style Assignments	Manage style assignments for a plan.
`/option-plan-masters/:id/supplier-assignments`	Supplier Assignments	Manage supplier choices tied to the plan.
`/option-plan-masters/:id/range-plan-previews`	Range Plan Previews	Preview downstream range-plan changes before commit.
`/option-plan-masters/:id_or_slug/push-to-range-board`	Push to Range Board	Send approved planning content into range planning.
`/option-plan-settings`	Option Plan Settings	Manage global option-plan configuration.
`/option-plan/write-with-ai/:slug`	AI Planning Notes	Generate AI-written commercial notes for a plan.

Data

Entity	Ownership	Description
Option Plan Master	owns	Top-level option planning workspace/master record addressed by id or slug.
Option Plan	owns	Individual option plan records under a master, exposed through CRUD APIs and gRPC detail retrieval.
Option Plan Settings	owns	Configurable settings for option planning behavior.
Approval Record	owns	Approval status and related transitions for option plan masters.
Style Assignment	owns	Assignments of manufacturing/style records to option plan masters, including latest-assignment lookup.
Supplier Assignment	owns	Supplier selections and supplier assignment options linked to option plans.
Range Plan Preview	owns	Preview records representing proposed downstream range-plan updates before commit.
Range Plan Push Job	owns	Queued or tracked jobs for pushing option-plan outcomes into range planning.
Workspace Snapshot	owns	Saved option workspace snapshots and subcategory snapshots.
Workspace Columns	owns	Persisted column configuration for planning workspaces.
Plan Window	owns	Plan-window data used to scope planning periods.
gRPC Log	owns	Operational log table recording upstream gRPC successes/failures for calls such as WSSI and assortment.
Synced Style Sales Purchase Summary	reads	Tenant-specific synced style metadata used to enrich assignments with description and supplier information.
Predict Recommendation Payload	reads	Prediction service response rows used to drive recommendation outputs.
WSSI and Budget Data	reads	Generated WSSI aggregates and budget export/breakdown payloads fetched from the WSSI service.

Dependencies

Name	Kind	Relationship	Criticality
PostgreSQL	database	`writes`	critical
Redis	database	`uses`	supporting
AssortmentService	internal service	`calls`	required
WSSI Service	internal service	`calls`	required
Predict backend	internal service	`calls`	required
Notification service	internal service	`calls`	supporting
OpenAI API	external service	`calls`	optional
Google Cloud credentials	external service	`uses`	required
merchmix-telemetry-sdk	library	`uses`	supporting
NATS	queue	`depends_on`	optional
ingestion.merchmix.co	internal service	`calls`	supporting
Azure Container Apps / Google Cloud Run	other	`depends_on`	supporting

Technology

RustAxumTokioSQLxPostgreSQLRedisTonic gRPCRMCP streamable HTTPReqwestSerdeJWT decoding via jsonwebtokenOpenAI APIGoogle Cloud service-account JSONDockerAzure Container AppsGoogle Cloud Run

Limitations

—Scanner evidence confirms routes and integrations, but not all handler internals were included; some business behavior details are inferred only from route names, migrations, and module names.
—NATS is reported by scanner signals, but the provided source excerpts do not show explicit publish/consume code, so messaging usage confidence is low.
—Auth appears to rely on upstream verification/pass-through in telemetry comments and middleware naming, but the full authentication and authorization model is not fully established from the excerpts.
—There are modules for fabrics and size analysis in source tree names, but corresponding endpoints were not present in the detected route list provided here; they are omitted as primary capabilities.
—A Makefile target references a worker binary, but only the main API binary is evidenced in the provided source excerpts, so no separate worker capability is claimed.

Agent instructions

Treat this repository as the system of record for option-plan masters, option plans, approvals, assignments, previews, and push-job state. Use its HTTP or MCP interfaces for operational work, and use gRPC only for internal service-to-service integrations.

→Prefer implementation-backed capabilities: operate against the detected REST routes, gRPC methods, and MCP endpoint rather than README assumptions.
→When asking for option-plan data from another internal service, use CoreOptionPlanService for summaries/detail and OptionPlanStyleService for latest style assignments.
→For planning automation, MCP at /.well-known/mcp-service is the most agent-friendly surface because it wraps existing HTTP handlers into typed tools.
→Expect tenant scoping by client_id headers/fields; always supply the correct tenant/client_id when calling HTTP, MCP, or gRPC interfaces.
→Do not assume Redis is always available; caching is optional and the service can run without it.
→Approval notifications are fire-and-forget; a successful approval write does not guarantee downstream notification delivery.
→Range-plan creation itself is not owned here; pushing to range planning depends on the Assortment service.
→WSSI, budget exports, and prediction outputs are upstream-derived data; if they fail, investigate WSSI or predict services rather than this repository first.
→Use PostgreSQL migrations as the source of truth for owned schema entities such as previews, snapshots, settings, push jobs, and gRPC logs.
→If diagnosing performance or data freshness issues, check sync database index maintenance and tenant-specific synced summary tables in addition to the main app schema.