Briefing-mpd
currentBriefing-mpd is a Django and Django REST Framework service that combines merchandise performance decisions (MPD) with a daily retail briefing dashboard. It reads style, final-style, analytical, snapshot, and competitor data from PostgreSQL-backed tables, calculates inventory and demand exceptions, exposes item-level decision APIs, and supports briefing feed approvals. It also includes snapshot-building and synchronization services, Redis configuration, and a vendored gRPC notification publisher.
Business summary
This service helps retail teams decide what to do with merchandise. It highlights products at risk of selling out, carrying too much stock, or experiencing unusual demand; compares pricing with competitors; and presents these findings in a daily briefing where users can review and approve or reject recommended actions.
Capabilities
6Lets merchandise teams review individual styles, understand their commercial impact, and record actions such as holding price, promoting, repricing, increasing price, or applying a permanent markdown.
The MPD application provides item listing and detail views, impact-matrix data, single decisions, bulk decision previews and submissions, and decision status. Decision actions are represented by constants including ACTION_NONE, ACTION_PERMANENT_MARKDOWN, ACTION_PRICE_INCREASE, ACTION_PROMO, and ACTION_REPRICING, with decisions persisted through the MpdDecision model.
Identifies products that may sell out, have excess stock, experience a demand spike, or suffer a demand drop so teams can focus on the most urgent issues.
The briefing snapshot schema stores weeks of cover, four-week rate of sale, sales variance, closing stock, on-order units, exception counts, revenue at risk, and boolean flags for stockout, overstock, demand spike, and demand drop. The implemented thresholds are below 2 weeks of cover, above 12 weeks of cover, and sales variance above or below 25%.
Provides a daily feed of product and category issues, commercial changes, and recommended actions for retail users to review.
The briefing application exposes a dashboard, scan operation, feed-item detail, and approval routes. Category-engine code generates market and change feed items from daily snapshot data, including category sales summaries, SKU counts, revenue concentration, and week-over-week observations.
Allows users to approve or reject actions proposed in the merchandise briefing, creating a review step before changes are accepted.
ApprovalDetailView, ApproveActionView, and RejectActionView are wired under the briefing URL configuration. The repository also defines approval-status event configuration and notification publishing support, although the supplied evidence does not show the complete approval persistence or event implementation.
Compares the retailer’s average selling prices with competitor prices by category and subcategory, showing price gaps and the amount of competitor coverage.
CompetitorRollup queries webscraping_productweeklysnapshot, webscraping_scrapedproduct, and webscraping_website tables for the latest weekly competitor prices. It calculates competitor average, minimum, and maximum prices, competitor counts, tracked product counts, and the percentage gap against supplied internal prices; it can build context for downstream language-model analysis.
Builds and refreshes a daily product-performance snapshot so briefing metrics can be calculated consistently and served quickly.
Snapshot builder code creates tenant-specific daily_briefing_snapshot tables and ingests analytical results using PostgreSQL COPY. It reads analytical and master metadata from configured database connections, supports a scan endpoint and a sync endpoint, and uses a shared database alias named merchmix_sync.
Workflows
4A user or agent inspects a style’s current performance, reviews its impact matrix, and records a merchandise action.
- 1.List available merchandise items through the MPD items endpoint.
- 2.Retrieve a style by style reference.
- 3.Retrieve the style’s impact matrix and decision status.
- 4.Submit a single decision or preview and submit a bulk decision.
- 5.Use the configured action values to represent the recommended commercial response.
The service calculates product and category exceptions and presents them as briefing feed items.
- 1.Read analytical and master merchandise data from configured PostgreSQL connections.
- 2.Calculate rate of sale, weeks of cover, demand variance, exception counts, and revenue at risk.
- 3.Write or refresh the tenant daily briefing snapshot.
- 4.Generate market and change category feed items from the snapshot.
- 5.Expose the briefing dashboard and individual feed items for review.
A reviewer evaluates a proposed briefing action and records the outcome.
- 1.Open an approval by its identifier.
- 2.Review the associated briefing information.
- 3.Approve or reject the proposed action.
- 4.Optionally publish a configured notification event through the vendored notification client.
The service creates category-level pricing context for merchandising analysis.
- 1.Read the latest competitor product weekly snapshot.
- 2.Aggregate competitor prices by category and subcategory.
- 3.Combine competitor averages with supplied internal average prices.
- 4.Calculate price gaps and return structured benchmarking context.
Architecture
A Django monolith-style microservice with separate MPD and briefing applications. HTTP views delegate business calculations to service modules, while Django ORM models and explicitly managed PostgreSQL tables provide persistence. The service is deployable as a Gunicorn container on Azure Container Apps or Google Cloud Run.
Interfaces
18| Kind | Identifier | Description |
|---|---|---|
| http | GET /health/ | Returns service health and identifies the MPD and briefing sections. |
| http | GET / | Returns a service status response with links to the MPD and briefing sections. |
| http | GET /mpd/items/ and GET /api/mpd/items/ | Lists MPD merchandise items. |
| http | GET /mpd/items/<style_ref>/ and GET /api/mpd/items/<style_ref>/ | Returns details for a merchandise style identified by style reference. |
| http | GET /mpd/items/<style_ref>/impact-matrix/ and GET /api/mpd/items/<style_ref>/impact-matrix/ | Returns impact-matrix information for a merchandise style. |
| http | POST /mpd/decision/ and POST /api/mpd/decision/ | Records a single merchandise decision. |
| http | POST /mpd/decision/bulk/ and POST /api/mpd/decision/bulk/ | Records bulk merchandise decisions. |
| http | POST /mpd/decision/bulk/preview/ and POST /api/mpd/decision/bulk/preview/ | Previews the result of a bulk merchandise decision before submission. |
| http | GET /mpd/decision/status/ and GET /api/mpd/decision/status/ | Returns merchandise decision status information. |
| http | GET /mpd/meta/ and GET /api/mpd/meta/ | Returns MPD metadata and configured decision information. |
| http | GET /api/briefing/ and GET /briefing/ | Returns the briefing dashboard. |
| http | GET /api/briefing/scan/ and GET /briefing/scan/ | Runs or retrieves briefing scan output. |
| http | GET /api/briefing/sync/ and GET /briefing/sync/ | Runs or retrieves briefing snapshot synchronization. |
| http | GET /api/briefing/feed/<id>/ and GET /briefing/feed/<id>/ | Returns a briefing feed item. |
| http | GET /api/briefing/approvals/<id>/ and GET /briefing/approvals/<id>/ | Returns an approval record or approval details. |
| http | POST /api/briefing/approvals/<id>/approve/ and POST /briefing/approvals/<id>/approve/ | Approves a briefing action. |
| http | POST /api/briefing/approvals/<id>/reject/ and POST /briefing/approvals/<id>/reject/ | Rejects a briefing action. |
| other | merchmix_notify gRPC publisher | Vendored notification-service client and generated protobuf/gRPC stubs for publishing configured domain events. |
Screens
7| Route | Name | Purpose |
|---|---|---|
/ | Service home | Shows service status and links to MPD and briefing sections. |
/health/ | Health check | Reports that the MPD and briefing service is running. |
/api/briefing/ | Briefing dashboard | Presents the daily merchandise briefing and its feed. |
/mpd/items/ | MPD item list | Provides the merchandise styles available for performance review. |
/mpd/items/<style_ref>/ | MPD item detail | Shows details for one style. |
/mpd/items/<style_ref>/impact-matrix/ | Impact matrix | Shows the commercial impact information used for a style decision. |
/admin/ | Django administration | Provides the framework administration interface. |
Data
8| Entity | Ownership | Description |
|---|---|---|
| MpdDecision | owns | Recorded merchandise performance decisions and their status for styles or decision scopes. |
| Style | reads | Merchandise style records used as the primary MPD item dimension. |
| FinalStyle | reads | Time- or scope-specific style performance records used to select the latest MPD data and decision context. |
| Daily briefing snapshot | owns | Tenant-specific daily SKU metrics including stock, sales, forecast, rate of sale, weeks of cover, pricing, suppliers, risk flags, exceptions, revenue at risk, and recommended actions. |
| FeedItem | owns | Generated briefing cards or feed entries for product, market, and change observations. |
| Approval | writes | Briefing action review records addressed by approval detail, approve, and reject routes. |
| Competitor product weekly snapshot | reads | External analytical competitor price observations grouped by category and subcategory. |
| Competitor scraped product and website | reads | Competitor product classification and website identity used in price rollups. |
Dependencies
10| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL application database | database | depends_on | critical |
| Analytical/shared synchronization PostgreSQL database | database | reads | critical |
| Redis | database | uses | supporting |
| Notification service | internal service | publishes | optional |
| Django REST Framework | library | uses | critical |
| Django | library | uses | critical |
| Pandas | library | uses | required |
| Gunicorn | library | uses | required |
| Azure Container Apps | other | uses | supporting |
| Google Cloud Run | other | uses | supporting |
Technology
Limitations
8- —The supplied source excerpt truncates mpd/services.py and does not include the MPD models, serializers, views, or briefing views, so exact request and response schemas cannot be established.
- —The repository exposes no GraphQL, queue consumer, CLI, or webhook contract in the supplied endpoint evidence.
- —NATS is reported by the scanner as messaging infrastructure, but no NATS client or concrete publish/consume code is shown in the supplied source; it should not be assumed to be an active integration.
- —Notification publishing is present as vendored infrastructure, but the supplied evidence does not prove which briefing events are actually emitted at runtime.
- —Competitor benchmarking code is implemented, but no dedicated competitor HTTP route is shown; it appears to be an internal service used by briefing generation or downstream context building.
- —Authentication and authorization behavior is not established by the supplied routes. Django authentication middleware is enabled, but no explicit API authentication policy is shown.
- —The dependency manifests omit pandas even though briefing services import it, which may cause deployment or runtime issues unless it is supplied transitively or through the actual build environment.
- —The repository contains both Azure and Google Cloud deployment configurations; the active production target cannot be determined from the source alone.
Agent instructions
Use this repository for MPD item analysis and decisions, daily merchandise exception briefings, briefing feed review, and approval workflows.
- →For style-level analysis, start with the MPD items endpoint, then retrieve the item impact matrix and decision status before proposing or recording an action.
- →Use only the defined action categories when creating decisions: none, permanent markdown, price increase, promotion, or repricing.
- →For briefing analysis, treat weeks of cover, demand variance, exception count, revenue at risk, and recommended action as the primary signals.
- →Include the tenant context expected by the service, especially the X-Tenant-Client-Id header, when calling tenant-specific endpoints.
- →Use bulk decision preview before submitting bulk decisions where possible.
- →Do not assume that a briefing recommendation has been executed merely because it appears in the feed; use the approval endpoints and decision status to verify its state.
- →Do not treat competitor benchmarking as a standalone public API unless the deployed views expose an additional route not present in the supplied routing evidence.
- →Avoid relying on undocumented response shapes; inspect serializers and views in the repository before automating against fields not listed here.