# calendarandstore

Calendarandstore 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

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Business Calendar Management | Planning | `production` | `write` | user_facing, agent_facing |
| Trading and Marketing Calendar Planning | Planning | `production` | `write` | user_facing, agent_facing |
| Store Directory Management | Products | `partial` | `write` | user_facing, agent_facing |
| Store Reporting | Reporting | `partial` | `read` | agent_facing |
| Storefront Imagery Access | Other | `partial` | `read` | agent_facing |
| Tenant-Scoped API Authentication and Authorization | Authentication | `production` | `execute` | user_facing, agent_facing, internal |

**Business Calendar Management** — Maintain dated business events such as holidays, supplier shutdowns, cut-offs, deadlines, and other events that affect retail activity.

**Trading and Marketing Calendar Planning** — Create and maintain annual retail planning calendars containing weekly themes, budgets, product drops, promotions, and other trading or marketing plans.

**Store Directory Management** — Create and manage retailer store records used alongside calendar and planning information.

**Store Reporting** — Provide store-level trading reports to help retail users inspect store performance and activity.

**Storefront Imagery Access** — Retrieve imagery or location-related information associated with retail stores.

**Tenant-Scoped API Authentication and Authorization** — Ensure users and agents can access only the retailer tenant, service, and actions they are authorized to use.

## Workflows

**Maintain a trading and marketing plan** — Create 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.

**Maintain business events** — 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.

**Use the service through an AI agent** — 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.

**Components:** calendar_stores_service Django project and WSGI/ASGI entrypoints, Django REST Framework routers and viewsets for calendars and stores, Django ORM models and migrations for calendar data, Django Admin for calendar master, calendar row, and business event administration, merchmix_authlib shared token validation and DRF authentication adapter, calendar_stores_service authentication and authorization modules, mcp_server operations manifest, async HTTP client, and MCP server, Database startup guard for environment-specific database-name allowlists

**Patterns:** RESTful viewsets with router-generated CRUD routes, Tenant-scoped data access, Manifest-driven MCP tool generation, Separate agent adapter process communicating over HTTP, Environment-driven deployment and configuration, Fail-closed authentication and database safety checks

## Interfaces

| 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

| 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

| 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

| 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

Python 3.12, Django 5.2, Django REST Framework 3.17, Gunicorn, PostgreSQL via psycopg2, Django ORM and migrations, PyJWT, ES256/JWKS and HS256 v2 authentication, requests, MCP Python SDK, gRPC and protobuf notification client, Docker, Google Cloud Run and Azure Container Apps deployment

## Limitations

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

## Source

| Field | Value |
|---|---|
| Repository | `calendarandstore` |
| Branch | `master` |
| Commit | `558c68b96eed` |
| Generated by | `gpt-5.6-luna` |

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