merchmix-wssi
currentmerchmix-wssi is a Rust multi-tenant backend for WSSI merchandise planning, exposing REST, gRPC, and MCP interfaces over a shared planning engine. It generates WSSI grids from tenant data sources, supports preview and commit/writeback workflows, manages active overrides and commit history in PostgreSQL, and includes adjacent services for budget export/sync, continuity grouping, dashboard analytics, and cube rebuild operations. The repository also contains a cube-builder job, monitoring job, shared formula/core libraries, and a WASM build of the planning engine.
Business summary
This service powers week-by-week retail planning views for different customers. It lets teams review planning numbers, test changes before saving them, commit approved overrides, export budget values, monitor data quality, and see supporting dashboards for buying and store performance. It also provides agent-friendly read access through MCP and system-to-system access through gRPC.
Capabilities
18Provides the core WSSI planning view so planners can see weekly metrics for a chosen brand, category, subcategory, store, or view.
Implements tenant-scoped WSSI payload generation through shared core logic used by REST handlers and gRPC `GenerateWssi`. Uses tenant configuration plus snapshot loading/query layers to build calendar headers and metric aggregates, with cache support and optional cube/shadow serving paths.
Lets users test planning changes and recalculate results before committing them.
Preview flows are implemented in the shared core/WASM engine and exposed through service-layer preview operations and MCP tools such as previewing WSSI changes. Uses scenario overlays and recalculation logic from `wssi-core` without persisting writeback changes.
Saves approved planning overrides so they become part of the tenant's committed planning data.
`/wssi/commit` and commit-related handlers build commit requests from preview/scenario overlays, persist commit batches and overrides in PostgreSQL, publish/write back result cells to tenant data stores, and optionally trigger cube rebuilds for affected platinum tables.
Lets teams review past planning commits, their overrides, and resulting values.
Exposes `/wssi/commits`, `/wssi/commits/:batch_id`, `/wssi/commits/:batch_id/overrides`, `/wssi/commits/:batch_id/results`, plus MCP planning tools for listing commits and reading commit details. Backed by PostgreSQL commit tables introduced in migrations.
Shows currently active overrides and supports restoring live values when overrides are no longer wanted.
Implements listing, summary, compare, group, backfill, restore, and restore-all endpoints under `/wssi/active-overrides`. Uses PostgreSQL table `wssi_active_overrides`, compares override values to live values with metric-specific tolerance logic, and can rebuild state from commit data.
Provides budget values and breakdowns for downstream budgeting workflows and exports.
Exposed by `/budget/export-values` and gRPC methods `GetBudgetExportValues` and `GetBudgetExportBreakdown`. Also includes job infrastructure for budget sync and streaming progress via `/budget/sync-jobs` endpoints.
Tracks long-running budget sync jobs and their progress.
Uses PostgreSQL-backed budget sync job tables/migrations and exposes list/detail/stream endpoints for sync jobs. Startup code reaps stale jobs from previous processes.
Helps planners build and manage continuity groups and continuity-based style selections.
Exposes `/continuity/groups`, `/continuity/groups/:id`, `/continuity/generate`, `/continuity/groups/:id/generate`, `/continuity/styles`, `/continuity/style/details`, `/continuity/style/details/grouped`, and `/continuity/style/images`. Uses Redis-backed caching for season options and planning payload generation for continuity slices.
Supports planning by season code, including available season options and generated season-based slices.
Implements `/season-code/options` and `/season-code/generate`, with logic to normalize hierarchy filters, derive season hierarchy keys, and cache season options in Redis.
Provides saved planning views and available metrics so users can work with standard planning layouts.
Exposes `/views`, `/views/:view_name`, and `/views/available-metrics`; migrations add `wssi_view_configs` tables and module metadata. MCP tools also list and retrieve views and style codes.
Provides supporting analytics for buying and store performance, such as markdown risk, growth pulse, stock aging, and traffic patterns.
Separate dashboard module exposes planning and store dashboard endpoints under `/dashboard/...`, executing tenant-scoped warehouse queries and cache-keyed filtered reads. Includes buying metrics and store-specific queries like staff sales, peak hours, traffic, and health.
Pushes planning data to an external forecast/FC process and tracks the sync as a job.
`sync_handlers::trigger_fc_sync` creates a PostgreSQL sync job, resolves retail week context, then spawns a background task calling `wssi_bigquery::fc_sync::execute_fc_sync`. Status persistence is handled through commit persistence tables.
Checks ERP data quality before it is used in planning workflows.
An `/api/validate-erp-data` endpoint exists and the data layer contains modules such as `data_validation` and `erp_mapping` in `wssi-bigquery`, indicating warehouse-side validation support.
Highlights missing inventory data needed for planning.
An `/inventory/missing` endpoint is registered. Evidence supports existence of an inventory exception interface, but implementation details were not included in the scanned source excerpt.
Rebuilds and inspects a tenant planning cube used to speed up planning reads.
Contains a dedicated `wssi-cube-builder` binary and API handlers that start Azure Container Apps Jobs, inspect execution status, and fetch logs through Azure ARM and Log Analytics. Main API supports cube-enabled, cube-shadow, and BigQuery-backed modes.
Lets AI agents safely inspect planning grids, metrics, commits, overrides, views, and style codes without exposing write actions.
Mounts a streamable HTTP MCP service with read-only tool routing. MCP server reuses tenant resolution, auth middleware, and the same service-layer operations as REST; docs and code explicitly exclude mutating actions like commit and cache flush.
Allows other systems to request WSSI outputs and budget exports programmatically.
Defines `WssiService` in `protos/wssi.proto` with RPCs `GenerateWssi`, `GetBudgetExportValues`, and `GetBudgetExportBreakdown`, implemented with tonic in `crates/wssi-api/src/grpc`.
Runs scheduled checks to detect data drops and trigger backup/notification workflows.
`wssi-monitoring` is a separate binary that reads tenant config, runs shared migrations, inspects commit-related data across tenants, detects drops, performs/skips backups, and emits notifications.
Workflows
5Serve a tenant-scoped planning grid for a selected hierarchy and year.
- 1.Resolve tenant from middleware/config.
- 2.Load snapshot/calendar context from warehouse-backed sources and caches.
- 3.Compile/evaluate planning metrics through shared core logic.
- 4.Return calendar headers and aggregates through REST, gRPC, or MCP.
Test overrides, then persist approved changes.
- 1.Load baseline snapshot for requested hierarchy/year.
- 2.Apply scenario patches in preview logic and recalculate values.
- 3.If approved, convert preview/scenario state into a commit request DTO.
- 4.Persist commit batch and overrides in PostgreSQL.
- 5.Write results back to warehouse/platinum tables and optionally rebuild cube tables.
- 6.Expose commit/audit records for later retrieval.
Inspect which overrides are active and revert them when needed.
- 1.Query active overrides for tenant/hierarchy/year/store.
- 2.Optionally compare stored override values with live values using tolerance rules.
- 3.Backfill or group active override state if required.
- 4.Restore one or all overrides to live values and update active override tables.
Start and track a long-running budget synchronisation process.
- 1.Create a sync job record in PostgreSQL.
- 2.Run background processing against warehouse/export logic.
- 3.Stream or poll job status through `/budget/sync-jobs` endpoints.
- 4.Mark stale jobs as reaped on API startup if a previous process died.
Run a tenant cube build job and inspect execution state.
- 1.Call internal cube job handler for a tenant.
- 2.Start Azure Container Apps Job for `wssi-cube-builder-<tenant>` unless one is already running.
- 3.Fetch execution status from Azure ARM.
- 4.Fetch execution logs from Azure Log Analytics.
Architecture
Workspace-based Rust system with shared planning libraries and multiple binaries. `wssi-api` is the main Axum service; `wssi-core` contains calculation, snapshot, overlay, period, and commit logic; `wssi-bigquery` provides warehouse/query/writeback adapters; `wssi-snapshot` defines snapshot source abstractions; `wssi-wasm` packages preview/commit engine functionality for browser or worker use; `wssi-cube-builder` and `wssi-monitoring` are separate operational binaries.
Interfaces
8| Kind | Identifier | Description |
|---|---|---|
| http | /health | Health check endpoint for the API service. |
| http | REST API under /wssi, /budget, /continuity, /season-code, /views, /dashboard, /inventory, /cache | Primary user/internal API for planning, commits, exports, dashboards, and operational actions. |
| grpc | wssi.WssiService | gRPC service exposing GenerateWssi and budget export/breakdown RPCs. |
| http | /.well-known/mcp-service | MCP service discovery endpoint. |
| http | MCP streamable HTTP service | Agent-facing read-only MCP server mounted in the same Axum app; code comments indicate `/mcp` even though only discovery route was scanner-detected. |
| cli | wssi-api | Main API binary. |
| cli | wssi-cube-builder | Operational job binary for full/incremental cube rebuilds. |
| cli | wssi-monitoring | Scheduled monitoring binary for data-drop detection and backup/notification flow. |
Screens
9| Route | Name | Purpose |
|---|---|---|
/views | Planning Views | List saved WSSI views and available layouts/metrics. |
/views/:view_name | Planning View Detail | Retrieve a named planning view configuration. |
/continuity/groups | Continuity Groups | List or create continuity planning groups. |
/continuity/groups/:id | Continuity Group Detail | Inspect or manage a specific continuity group. |
/season-code/options | Season Code Options | Show selectable season codes for planning filters. |
/dashboard/buying/growth-pulse | Buying Growth Pulse | Show buying trend analytics. |
/dashboard/buying/markdown-risk | Markdown Risk Dashboard | Show markdown exposure analytics. |
/dashboard/planning/category-otb | Category OTB Dashboard | Show category open-to-buy planning metrics. |
/dashboard/stores/health | Store Health Dashboard | Show store-level health indicators. |
Data
12| Entity | Ownership | Description |
|---|---|---|
| WSSI Commit Batch | owns | Header record for a planning commit, including status and audit metadata. |
| WSSI Commit Override | owns | Per-cell or per-metric override records associated with a commit batch. |
| WSSI Commit Publish State | owns | Publish tracking/state for committed results. |
| Sync Job | owns | Operational job records for forecast sync and budget sync processing. |
| Budget Sync Job | owns | Tracked budget synchronisation jobs and progress streams. |
| Continuity Group | owns | Tenant continuity grouping records introduced by dedicated migrations. |
| WSSI View Configuration | owns | Saved view definitions and associated module metadata. |
| Active Override | owns | Current live set of active overrides by tenant, hierarchy, year, and optional store. |
| Tenant Configuration | reads | Per-tenant connection and behavior settings loaded from `config.json` or configured path. |
| Warehouse Planning Snapshot | reads | Baseline planning metrics, calendars, hierarchy, and supporting analytical tables queried through the BigQuery/Databricks client layer. |
| Cube Tables | writes | PostgreSQL-backed cube structures built by cube migrations and builder jobs for faster serving/parity modes. |
| Redis Cache Entries | writes | Cached payloads, preview sessions, styles, metric UI data, and season options. |
Dependencies
11| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL | database | writes | critical |
| Databricks warehouse | database | reads | critical |
| Redis | database | uses | required |
| Azure Container Apps / ARM | external service | calls | required |
| Azure Log Analytics | external service | calls | supporting |
| Google APIs / GCP auth | external service | authenticates_through | required |
| NATS | queue | depends_on | optional |
| wssi-core | library | depends_on | critical |
| wssi-bigquery | library | depends_on | critical |
| wssi-formula | library | depends_on | required |
| Bitbucket API | external service | calls | supporting |
Technology
Limitations
5- —The scanner lists many HTTP routes but not HTTP methods for each, so some read/write classifications are inferred from handler names and code.
- —Evidence clearly supports WSSI generation, commit history, active overrides, dashboards, budget export, cube jobs, and MCP; some endpoints such as `/inventory/missing` and `/api/validate-erp-data` had limited implementation detail in the excerpt.
- —The data signal says `bigquery`, but current code comments explicitly describe a Databricks warehouse client behind `BigQueryClient`; the exact runtime warehouse mix may vary by tenant or legacy naming.
- —NATS was detected as a messaging signal, but no concrete publisher/consumer code was shown in the provided source excerpt.
- —Auth exists (`auth_middleware`, JWT dependency), but the exact identity provider and authorization model were not established from the supplied evidence.
Agent instructions
Use this repository as the source of truth for WSSI planning reads, previews, commits, override audits, budget export, and related dashboards. Prefer shared service/core modules over duplicating transport-specific logic.
- →For business questions, frame this repo as the backend for WSSI planning and related audit/export workflows, not just an API server.
- →When tracing behavior, start in `crates/wssi-api/src/main.rs` for routing/middleware, then follow into `services`, `handlers`, and finally `wssi-core` for calculation logic.
- →Treat `wssi-core` as the canonical engine for preview, commit, overlays, period folding, and formula evaluation.
- →For read-only agent integrations, prefer MCP tools and service-layer functions; do not propose mutating MCP actions because code explicitly excludes them.
- →For commit/audit issues, inspect PostgreSQL migrations and commit-related repositories/tables before assuming a warehouse problem.
- →For data discrepancies in generated grids, compare BigQuery/Databricks snapshot loading, cache behavior, and cube shadow/enable settings.
- →For cube issues, inspect both API-side cube handlers and the separate `wssi-cube-builder` job binary; Azure job status/log retrieval is part of this repo.
- →Do not rely solely on README claims; validate capabilities against routes, migrations, and crate usage in code.
- →If asked about frontend parity or regressions, note the golden fixture tests that freeze generate/commit/commit-read contracts.
- →Be cautious with tenant-specific behavior: tenant configuration is loaded from `config.json` or `TENANTS_JSON_PATH`, and most operations are tenant-scoped via middleware.