# Briefing-mpd

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

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Merchandise Performance Decisioning | Planning | `production` | `write` | user_facing, agent_facing |
| Inventory and Demand Exception Monitoring | Inventory | `production` | `read` | user_facing, agent_facing |
| Daily Merchandise Briefing | Reporting | `production` | `read` | user_facing |
| Briefing Recommendation Approval | Planning | `partial` | `write` | user_facing, agent_facing |
| Competitor Price Benchmarking | Reporting | `partial` | `read` | user_facing, internal |
| Briefing Snapshot Synchronization | Reporting | `production` | `execute` | agent_facing, internal |

**Merchandise Performance Decisioning** — Lets 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.

**Inventory and Demand Exception Monitoring** — 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.

**Daily Merchandise Briefing** — Provides a daily feed of product and category issues, commercial changes, and recommended actions for retail users to review.

**Briefing Recommendation Approval** — Allows users to approve or reject actions proposed in the merchandise briefing, creating a review step before changes are accepted.

**Competitor Price Benchmarking** — Compares the retailer’s average selling prices with competitor prices by category and subcategory, showing price gaps and the amount of competitor coverage.

**Briefing Snapshot Synchronization** — Builds and refreshes a daily product-performance snapshot so briefing metrics can be calculated consistently and served quickly.

## Workflows

**Review and act on an MPD item** — A 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.

**Generate and review the daily briefing** — 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.

**Approve or reject a briefing action** — 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.

**Compare internal and competitor pricing** — 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.

**Components:** mpd Django app for item retrieval, impact matrices, decisions, bulk previews, decision submission, metadata, and decision status., briefing Django app for dashboard, scan, synchronization, feed items, and approval actions., briefing/services/builder.py for analytical snapshot construction and PostgreSQL COPY ingestion., briefing/services/category_engine.py for category-level market and change feed generation., briefing/services/competitor.py for competitor price aggregation and pricing context., common Django app for shared models and views., merchmix_ai.sync_tables for tenant-aware synchronization table naming., merchmix_notify for vendored gRPC notification publishing and recipient resolution., mpd_briefing_service Django project for settings, routing, WSGI, ASGI, health, and deployment runtime.

**Patterns:** Django class-based API views with Django REST Framework responses., Service-layer business logic around Django ORM and direct SQL., Tenant-aware routing and table resolution using the X-Tenant-Client-Id request header and tenant-specific snapshot tables., Separate analytical/synchronization database connection from the default application database., PostgreSQL bulk ingestion using COPY., Containerized deployment behind Gunicorn.

## Interfaces

| 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

| 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

| 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

| 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

Python 3.12, Django 5.2, Django REST Framework, PostgreSQL, Django ORM, Direct PostgreSQL SQL and COPY ingestion, Redis and django-redis, Pandas, gRPC and Protocol Buffers, Gunicorn, Docker, Azure Container Apps, Google Cloud Run, WhiteNoise, django-cors-headers

## Limitations

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

## Source

| Field | Value |
|---|---|
| Repository | `Briefing-mpd` |
| Branch | `main` |
| Commit | `2a89d6d8e112` |
| Generated by | `gpt-5.6-luna` |

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