# merchmix-wssi

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

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| WSSI Planning Grid Generation | Planning | `production` | `read` | user_facing, agent_facing |
| What-If Planning Preview | Planning | `production` | `execute` | user_facing, agent_facing |
| Plan Override Commit | Planning | `production` | `write` | user_facing, internal |
| Commit History and Audit Retrieval | Reporting | `production` | `read` | user_facing, agent_facing |
| Active Override Management | Planning | `production` | `write` | user_facing, agent_facing |
| Budget Export | Planning | `production` | `read` | user_facing, internal |
| Budget Synchronisation Job Tracking | Planning | `production` | `execute` | user_facing, internal |
| Continuity Group Planning | Planning | `production` | `write` | user_facing |
| Season Code Planning Support | Planning | `production` | `read` | user_facing |
| View Configuration Management | Planning | `production` | `read` | user_facing, agent_facing |
| Retail Dashboard Analytics | Reporting | `production` | `read` | user_facing |
| Forecast Data Synchronisation | Forecasting | `partial` | `execute` | internal |
| ERP Data Validation | Other | `partial` | `execute` | internal |
| Inventory Exception Reporting | Inventory | `partial` | `read` | user_facing |
| Cube Build Operations | Planning | `production` | `execute` | internal |
| Agent Read Access via MCP | Other | `production` | `read` | agent_facing |
| System Integration via gRPC | Other | `production` | `read` | internal |
| Commit Data Monitoring | Reporting | `internal_only` | `execute` | internal |

**WSSI Planning Grid Generation** — Provides the core WSSI planning view so planners can see weekly metrics for a chosen brand, category, subcategory, store, or view.

**What-If Planning Preview** — Lets users test planning changes and recalculate results before committing them.

**Plan Override Commit** — Saves approved planning overrides so they become part of the tenant's committed planning data.

**Commit History and Audit Retrieval** — Lets teams review past planning commits, their overrides, and resulting values.

**Active Override Management** — Shows currently active overrides and supports restoring live values when overrides are no longer wanted.

**Budget Export** — Provides budget values and breakdowns for downstream budgeting workflows and exports.

**Budget Synchronisation Job Tracking** — Tracks long-running budget sync jobs and their progress.

**Continuity Group Planning** — Helps planners build and manage continuity groups and continuity-based style selections.

**Season Code Planning Support** — Supports planning by season code, including available season options and generated season-based slices.

**View Configuration Management** — Provides saved planning views and available metrics so users can work with standard planning layouts.

**Retail Dashboard Analytics** — Provides supporting analytics for buying and store performance, such as markdown risk, growth pulse, stock aging, and traffic patterns.

**Forecast Data Synchronisation** — Pushes planning data to an external forecast/FC process and tracks the sync as a job.

**ERP Data Validation** — Checks ERP data quality before it is used in planning workflows.

**Inventory Exception Reporting** — Highlights missing inventory data needed for planning.

**Cube Build Operations** — Rebuilds and inspects a tenant planning cube used to speed up planning reads.

**Agent Read Access via MCP** — Lets AI agents safely inspect planning grids, metrics, commits, overrides, views, and style codes without exposing write actions.

**System Integration via gRPC** — Allows other systems to request WSSI outputs and budget exports programmatically.

**Commit Data Monitoring** — Runs scheduled checks to detect data drops and trigger backup/notification workflows.

## Workflows

**Generate WSSI grid** — Serve 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.

**Preview and commit planning changes** — 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.

**Review active overrides and restore live values** — 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.

**Run a budget sync job** — 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.

**Trigger cube rebuild for a tenant** — 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.

**Components:** `crates/wssi-api`: main HTTP/gRPC/MCP API, auth, tenant routing, handlers, services, caches, budget jobs, dashboard, cube operations, `crates/wssi-core`: planning engine for compile/evaluate/preview/commit/period folding/overlays, `crates/wssi-bigquery`: warehouse client and modules for queries, sync, validation, metric definitions, lineage, writeback, cube support, `crates/wssi-snapshot`: snapshot source trait and in-memory/bigquery-backed loading support, `crates/wssi-types`: shared DTOs and domain types, `crates/wssi-formula`: formula parsing and dependency extraction, `crates/wssi-wasm`: WASM wrapper around preview/commit engine, `crates/wssi-cube-builder`: job binary to rebuild cube tables, `crates/wssi-monitoring`: scheduled monitoring and backup/notification job

**Patterns:** Workspace monorepo with reusable crates, Transport adapters over shared service/core logic, Multi-tenant request handling via middleware and tenant config, PostgreSQL for operational state plus warehouse-backed analytical reads, Background job pattern for sync/rebuild work, Read-only MCP facade over existing service methods, Optional cache providers with Redis and in-memory fallbacks

## Interfaces

| 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

| 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

| 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

| 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

Rust, Axum, Tonic gRPC, MCP via rmcp streamable HTTP, SQLx, PostgreSQL, Redis, Reqwest, Tokio, Protobuf, WASM via wasm-bindgen, Docker, Azure Container Apps, Databricks/warehouse access through custom `wssi-bigquery` crate

## Limitations

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

## Source

| Field | Value |
|---|---|
| Repository | `merchmix-wssi` |
| Branch | `master` |
| Commit | `1a6e9d9ac17c` |
| Generated by | `gpt-5.4` |

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