calendarandstore
currentCalendarandstore is a Django and Django REST Framework service for MerchMix calendar and store-management data. It exposes business-calendar and trading-and-marketing calendar APIs, store operations, administrative screens, and a separate MCP server that converts the HTTP API into agent tools. Requests are tenant-scoped and support MerchMix authentication and service/permission authorization.
Business summary
This service helps retailers maintain the dates and weekly plans that coordinate trading, marketing, budgets, promotions, and operational deadlines. It also provides a store directory and store-related information so retail teams and AI agents can work with calendars and stores in one place.
Capabilities
6Maintain dated business events such as holidays, supplier shutdowns, cut-offs, deadlines, and other events that affect retail activity.
Implemented by BusinessCalendarEventViewSet and the business calendar summary and timezone endpoints. The model is administered through Django Admin, with fields including event type, country, region, start and end dates, trading impact, supply impact, status, description, and required action.
Create and maintain annual retail planning calendars containing weekly themes, budgets, product drops, promotions, and other trading or marketing plans.
Implemented through TradingMarketingMasterViewSet and TradingMarketingCalendarViewSet. CalendarMaster stores tenant, name, department, category, status, calendar year, financial year, creator, and slug; Calendar stores dated planning rows linked to a master, including budget and marketing-related fields. Summary endpoints expose whether business or trading-marketing data exists.
Create and manage retailer store records used alongside calendar and planning information.
A StoreViewSet is registered under the stores prefix and is mounted at both /api/calendar/stores and /calendar/stores, with optional trailing slashes. The scanner explicitly identifies the store creation endpoint; the MCP source describes broader store-directory operations, but the complete Store model and route list are not included in the supplied source excerpt.
Provide store-level trading reports to help retail users inspect store performance and activity.
The MCP server instructions identify ten per-store trading reports and distinguish empty report results from unavailable warehouse tables. Reports are described as read-only and anchored to a store's last activity. The underlying report routes and implementation are not present in the supplied Django endpoint list.
Retrieve imagery or location-related information associated with retail stores.
The MCP server instructions identify storefront imagery endpoints and warn that image calls may incur Google charges. Google Maps and Places hosts are referenced by the repository. The corresponding Django routes and image model are not included in the supplied endpoint or source excerpts.
Ensure users and agents can access only the retailer tenant, service, and actions they are authorized to use.
Authentication supports Auth Service-backed context resolution and vendored MerchMix JWT validation components, including ES256/JWKS and HS256 v2 paths. Tenant routing uses X-Tenant-Client-Id by default; authorization checks service entitlement and action permissions such as calendar:create. A recovery mode can bypass bearer-token validation while retaining supported-tenant validation and tenant-scoped queries.
Workflows
3Create a yearly planning master and manage its dated planning rows.
- 1.Create a trading and marketing master for a tenant, department, category, and calendar year.
- 2.Add or update dated calendar rows containing weekly planning and marketing information.
- 3.Review the trading and marketing summary or retrieve calendar rows.
- 4.Use the Django Admin or MCP tools when those interfaces are enabled.
Record operational or market events that affect retail planning.
- 1.Create a business calendar event with dates, location, impacts, and status.
- 2.Retrieve business calendar events or the business-calendar summary.
- 3.Use the event information when coordinating trading, supply, and marketing activity.
Expose the Calendar and Stores HTTP API as tenant-aware MCP tools.
- 1.Start the separate MCP server over stdio or a supported network transport.
- 2.Configure the target base URL and default tenant, or provide tenant_id per call.
- 3.Read calendar, store, reporting, or imagery information through generated tools.
- 4.Enable the explicit MCP write setting before using write operations.
Architecture
A Django monolith serves the Calendar and Stores API through Django REST Framework viewsets and function-based summary endpoints. A separate MCP process acts as an HTTP client and generates agent tools from an operations manifest rather than importing Django.
Interfaces
13| Kind | Identifier | Description |
|---|---|---|
| http | GET / | Service home or health-style landing endpoint. |
| http | GET /api/calendar/business/ and GET /calendar/business/ | Business calendar summary. |
| http | GET /api/calendar/business/timezones/ and GET /calendar/business/timezones/ | Business-calendar timezone information. |
| http | POST /api/calendar/business/events/ and POST /calendar/business/events/ | Create business calendar events. |
| http | GET/POST/PATCH/PUT/DELETE /api/calendar/business/events/ | Router-backed business calendar event operations; the supplied scanner explicitly confirms the GET and POST routes. |
| http | GET /api/calendar/trading-marketing/ and GET /calendar/trading-marketing/ | Trading and marketing calendar summary. |
| http | POST /api/calendar/trading-marketing/masters/ and POST /calendar/trading-marketing/masters/ | Create trading and marketing calendar masters. |
| http | GET /api/calendar/trading-marketing/calendars/ | Retrieve trading and marketing calendar rows. |
| http | GET/POST/PATCH/PUT/DELETE /api/calendar/trading-marketing/masters/ and /api/calendar/trading-marketing/calendars/ | Router-backed trading and marketing master and row operations; the supplied scanner confirms the listed GET and POST routes. |
| http | POST /api/calendar/stores and POST /calendar/stores | Create store records. The custom router accepts an optional trailing slash. |
| http | admin/ | Django Admin interface for calendar masters, calendar rows, and business events. |
| sdk | MCP server: python -m mcp_server.server | Agent-facing MCP server that generates tools from mcp_server.operations and calls the HTTP API. |
| other | MCP stdio, streamable-http, or SSE transport | Supported MCP serving transports configured through environment variables. |
Screens
2| Route | Name | Purpose |
|---|---|---|
/ | Service Home | Landing endpoint for the service. |
/admin/ | Calendar and Stores Admin | Administrative management of calendar masters, planning rows, and business calendar events. |
Data
6| Entity | Ownership | Description |
|---|---|---|
| CalendarMaster | owns | Tenant-scoped trading and marketing planning master with name, department, category, status, creator, calendar year, financial year, slug, and timestamps. |
| Calendar | owns | Dated planning row linked to a CalendarMaster, including sales budget and special dates, drops, shoots, themes, marketing, and related weekly planning fields. |
| BusinessCalendarEvent | owns | Tenant-scoped dated business event with title, event type, geography, description, trading and supply impacts, status, and action-required information. |
| Store | writes | Store directory record exposed through StoreViewSet. The supplied source confirms the store route but does not include the complete model definition. |
| Store trading reports | reads | Read-only per-store report results sourced from a warehouse; reports can be empty or unavailable when a tenant warehouse table is missing. |
| Tenant and authorization context | reads | Tenant identifier, user identity, roles, groups, services, permissions, token claims, and impersonation context used to scope and authorize requests. |
Dependencies
8| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| MerchMix Auth Service | internal service | authenticates_through | critical |
| merchmix_authlib | library | uses | critical |
| PostgreSQL-compatible database | database | reads | critical |
| Databricks or warehouse connection | database | reads | required |
| Google Maps and Places APIs | external service | calls | optional |
| Redis | database | uses | supporting |
| NATS | queue | uses | supporting |
| Notification service | internal service | publishes | optional |
Technology
Limitations
7- —The supplied source excerpt does not include the complete stores app implementation, Store model, serializers, or store viewset.
- —The deterministic HTTP endpoint list confirms only a subset of the router-generated CRUD operations; the exact route and request/response schema for every calendar and store operation cannot be established here.
- —Store reports and storefront imagery are explicitly described by the MCP server source, but their underlying service routes and data models are not present in the supplied endpoint list.
- —The scanner reports Redis, Redis TLS, Databricks, and NATS signals, but the supplied source does not show which specific code paths use each dependency.
- —Authentication has a configurable recovery bypass. When MERCHMIX_AUTH_ENABLED is disabled, bearer tokens are not validated and service/action permission checks are skipped, although tenant-header validation and tenant scoping remain enforced.
- —No evidence establishes forecasting, OTB, WSSI, replenishment, allocation, markdown, buying, or assortment-planning calculations in this repository.
- —MCP write safety behavior is described in source documentation and server instructions, but the supplied excerpt does not include the full operations manifest or all confirmation rules.
Agent instructions
Use this repository for tenant-scoped retail calendars and store information, not for merchandise calculations such as forecasting, OTB, allocation, or replenishment.
- →Always provide or preserve the tenant routing context, normally through X-Tenant-Client-Id or the MCP tenant_id setting.
- →Treat business calendar events and trading-marketing calendar rows as different data types: business events are dated operational events, while trading-marketing calendars are weekly planning grids.
- →Use the returned fiscal-year and retail-week fields rather than calculating week numbers independently.
- →When using MCP, keep writes disabled unless a user explicitly requests a write and the MCP server is configured with CALENDAR_STORES_MCP_ALLOW_WRITES=true.
- →Prefer PATCH-style update tools over replacement operations when working through MCP, where available.
- →Do not interpret an unavailable store report as zero sales or no activity; distinguish empty results from unavailable warehouse data.
- →Avoid broad image retrieval across stores because the repository warns that Google-backed image calls may incur per-call costs.
- →Do not infer support for WSSI, OTB, forecasting, allocation, replenishment, markdown, buying, or assortment planning from the calendar data alone.