# criticalpath

Criticalpath is a multi-tenant Django REST service for managing retail product launch schedules and operational task work. It provides reusable critical-path templates, date-based plans, task and subtask management, collaboration features, range-plan visibility, exports/imports, and workload views. It also includes a separate MCP server that exposes the service API as assistant tools.

## Business Summary

This service helps a retailer plan everything that must happen before a product launches, such as sourcing, freight, reviews, and other launch activities. Teams can start from reusable schedules, assign and track work, see workload and board views, collaborate through checklists and comments, and connect launch work to range plans.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Critical Path Planning | Planning | `production` | `write` | user_facing, agent_facing |
| Critical Path Template Management | Planning | `production` | `write` | user_facing, agent_facing |
| Task and Subtask Management | Planning | `production` | `write` | user_facing, agent_facing |
| Task Workflow and Status Tracking | Planning | `production` | `write` | user_facing, agent_facing |
| Workload and Work Assignment Visibility | Reporting | `production` | `read` | user_facing, agent_facing |
| Task Collaboration | Planning | `production` | `write` | user_facing, agent_facing |
| Range Plan Integration | Planning | `partial` | `execute` | user_facing, agent_facing, internal |
| Planning Data Import and Export | Reporting | `production` | `execute` | user_facing, agent_facing |
| Module Link Management | Planning | `production` | `read` | user_facing, agent_facing |
| Tenant-Scoped Access Control | Authentication | `production` | `execute` | user_facing, agent_facing, internal |
| Assistant API Access | Other | `production` | `execute` | agent_facing |

**Critical Path Planning** — Create and manage countdown plans that coordinate the work required to bring merchandise to the shop floor by a launch date.

**Critical Path Template Management** — Create, reuse, duplicate, inspect, and export standard launch schedules for recurring merchandise processes.

**Task and Subtask Management** — Create, view, update, delete, assign, and track the individual pieces of work within a launch plan.

**Task Workflow and Status Tracking** — Organize work by status and monitor progress across launch activities.

**Workload and Work Assignment Visibility** — Help managers and teams understand who is responsible for work and how work is distributed.

**Task Collaboration** — Keep supporting work details and team discussion attached to launch tasks.

**Range Plan Integration** — View range plans and their items while incorporating range-plan information into critical-path planning.

**Planning Data Import and Export** — Move plan and template information in and out of the service for reuse, reporting, and migration.

**Module Link Management** — Resolve links from critical-path work to related Merchmix product-planning modules.

**Tenant-Scoped Access Control** — Keep each retailer or tenant's plans, tasks, and related data separated while allowing authorized users to work within their tenant.

**Assistant API Access** — Allow an AI assistant to inspect and drive critical-path and task-list workflows through structured tools.

## Workflows

**Create a launch plan from a reusable schedule** — Turn a standard template into a dated critical-path plan for a merchandise launch.

1. List available templates.
2. Create a plan or save an existing plan as a template.
3. Generate or populate plan tasks using stage offsets relative to the launch date.
4. Review tasks and dependencies.
5. Use bulk date shifting when the plan schedule needs to move.

**Manage launch work** — Create and maintain the tasks that make up a critical path.

1. Create tasks and subtasks.
2. Assign work to users.
3. Update task details and statuses.
4. Use board, grouped-status, filtered-list, and workload views to monitor progress.
5. Add checklist items or comments and reorder or bulk-update tasks as needed.

**Connect planning data to launch execution** — Bring range-plan context into a critical-path plan.

1. List available range plans.
2. Preview the items for a selected range plan.
3. Import range-plan data into a plan.
4. Continue managing the resulting launch work through task and status workflows.

**Use the API through an AI assistant** — Operate the service through MCP tools while preserving tenant scope.

1. Configure the MCP base URL and default tenant.
2. Optionally provide a bearer token where authentication is enforced.
3. Orient with the critical-path overview, plans, templates, and assignees.
4. Read or execute generated Critical Path and Task List tools.
5. Treat timeout responses on slow writes cautiously because the underlying request may still complete.

## Architecture

A Django 5.2 application exposes two related REST API areas: critical_path for launch plans and task_list for operational task management. It runs behind Gunicorn in Docker/Cloud Run or Azure Container Apps, uses Django ORM for persistence, Redis for caching, and tenant-aware authentication and authorization middleware/permissions. An independently provisioned MCP process acts as an HTTP client and tool generator over the REST API.

**Components:** critical_path Django app containing plan, template, range-plan, module-link, task, and subtask views, task_list Django app containing legacy and v2 task-list, board, workload, checklist, comment, reorder, and bulk-update views, critical_path_service Django project containing settings, WSGI/ASGI entry points, authentication, tenanting, permissions, exception mapping, and database startup safeguards, Vendored merchmix_authlib for ES256 token validation, tenant resolution, JWKS access, service entitlement, and permission checks, Vendored merchmix_notify package for notification publishing and recipient resolution, mcp_server client, operations catalog, and MCP server for generated assistant tools, Django ORM database layer with PostgreSQL support and Redis-backed caching, Docker and CI/CD deployment definitions for Google Cloud Run and Azure Container Apps

**Patterns:** Django REST Framework class-based API views, Tenant isolation using a trusted request header and tenant-scoped data access, Centralized authentication with a temporary tenant-only fallback gate when Auth Service enforcement is disabled, Generated MCP tools from a single operation catalog, Per-tenant HTTP cache variation using X-Tenant-Client-Id, Environment-driven integration endpoints and deployment configuration, Database startup guard requiring environment-specific database-name allowlists

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `http` | `GET/POST /api/critical-path/` | Critical-path API including plans, templates, range plans, module links, tasks, and subtasks. Legacy /critical-path/ and selected shorthand routes are also registered. |
| `http` | `GET/POST /api/task-list/` | Task-list API including users, tasks, statuses, board, workload, current-user work, bulk updates, reordering, checklists, and comments. Legacy /task-list/ and /ai-recommends/ compatibility prefixes are also registered. |
| `http` | `GET /health/` | Health/status endpoint returning service availability information. |
| `http` | `GET /` | Service home/status endpoint identifying the Critical Path and Task List sections. |
| `http` | `GET /admin/` | Django administration interface. |
| `sdk` | `mcp_server.server` | MCP server exposing generated Critical Path and Task List tools over stdio, streamable HTTP, or SSE according to MCP configuration. |
| `http` | `Auth Service context endpoint` | Configured authentication integration used to obtain authorization context; the default path is /settings/auth/context/ on the configured Auth Service base URL. |
| `other` | `Notification publisher` | Vendored gRPC notification client integration is available for publishing service events, with configuration controlled by notification environment settings. |

## Screens

| Route | Name | Purpose |
|---|---|---|
| `/plans/` | Critical Path Plans | List and create launch plans. |
| `/plans/<id>/` | Plan Detail | Inspect and update a specific launch plan. |
| `/templates/` | Critical Path Templates | List reusable launch schedules. |
| `/templates/create/` | Create Template | Create a reusable schedule template. |
| `/range-plans/` | Range Plans | List range plans available for critical-path use. |
| `/task-list/v2/board/` | Task Board | View task work in board form. |
| `/task-list/v2/workload/` | Workload | View work distribution and workload information. |
| `/task-list/v2/my-work/` | My Work | View tasks associated with the current user. |
| `/admin/` | Django Admin | Administrative management of service data and configuration. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| Critical Path Plan | `owns` | A dated launch plan containing the work required to reach a merchandise launch. |
| Critical Path Template | `owns` | A reusable schedule definition for generating or standardizing launch plans. |
| Task | `owns` | An actionable unit of launch or operational work, with status and assignment information. |
| Subtask | `owns` | A subordinate work item associated with a task. |
| Task Checklist Item | `owns` | A checklist entry attached to a task. |
| Task Comment | `owns` | Collaboration discussion attached to a task. |
| Range Plan | `reads` | Range-planning data exposed for listing, item preview, and import into plans; the source system may be external. |
| Range Plan Item | `reads` | An item within a range plan used for preview or plan import. |
| Module Link | `owns` | A tenant/module-specific link or resolved destination for related Merchmix planning modules. |
| User/Assignee Reference | `reads` | User information used to list possible assignees and associate work with people; the authoritative user directory may be external. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL-compatible database | `database` | `depends_on` | `critical` |
| Redis | `database` | `uses` | `required` |
| Merchmix Auth Service | `internal_service` | `calls` | `required` |
| Merchmix notification service | `internal_service` | `publishes` | `optional` |
| Assortment / Range Planning service | `internal_service` | `calls` | `supporting` |
| Budget Builder service | `internal_service` | `uses` | `supporting` |
| Option Planning service | `internal_service` | `uses` | `supporting` |
| Product Review service | `internal_service` | `uses` | `supporting` |
| WSSI service | `internal_service` | `uses` | `supporting` |
| MCP SDK | `library` | `depends_on` | `optional` |
| OpenPyXL | `library` | `uses` | `supporting` |
| Django REST Framework | `library` | `depends_on` | `critical` |

## Technology

Python 3.12, Django 5.2, Django REST Framework, PostgreSQL via psycopg2-binary, Redis and django-redis, PyJWT and cryptography for ES256 authentication, Requests, OpenPyXL, gRPC and Protobuf notification client support, MCP SDK in a separate environment, Gunicorn, WhiteNoise, Docker, Google Cloud Run and Azure Container Apps deployment

## Limitations

- The supplied source excerpt does not include model definitions, serializers, view implementations, or migrations, so exact field-level schemas and persistence relationships cannot be established.
- The scanner lists NATS messaging, but the supplied source does not show a concrete NATS publisher or consumer; no NATS business workflow is asserted.
- External module hosts and environment settings establish integration configuration, but the excerpt does not prove the full behavior or availability of each downstream service.
- Notification publishing is evidenced by vendored client code and package documentation, but concrete event call sites were not included in the supplied source excerpt.
- The MCP documentation describes 41 tools, while the scanner's route summary shows only a subset of methods/routes; exact generated tool names and complete operation coverage should be confirmed from mcp_server/operations.py.
- Authentication includes a documented temporary tenant-only fallback mode; deployment settings determine whether centralized Auth Service enforcement is active.

## Agent Instructions

Use this repository for retailer launch planning, critical-path scheduling, and operational task management. Keep every operation tenant-scoped and distinguish plan scheduling from task execution and collaboration.

- Require or preserve the trusted X-Tenant-Client-Id tenant context for API calls; never infer tenant scope from arbitrary user input or data returned by another tenant.
- For launch planning, inspect templates and existing plans before creating a new plan to avoid duplicate schedules.
- Remember that critical-path dependencies are recorded, while dates are derived from stage offsets; moving one task does not automatically cascade successor dates. Use the bulk-shift operation when the whole plan must move.
- For task operations, prefer the v2 task-list routes when filtering, board, workload, bulk update, reorder, checklist, or comment behavior is needed; use legacy routes only for compatibility.
- Treat range-plan and module-link data as integration-backed or read-only unless the concrete endpoint implementation confirms otherwise.
- For MCP writes, use the configured tenant and token and handle timeout responses carefully: a slow write may have completed even if the MCP client timed out.
- Do not expose or request secret values, tokens, database credentials, or environment-file contents.
- When exact fields, statuses, permissions, or side effects matter, inspect the relevant Django view, serializer, model, and operation definition rather than relying on route names alone.

## Source

| Field | Value |
|---|---|
| Repository | `criticalpath` |
| Branch | `master` |
| Commit | `1876045fe603` |
| Generated by | `gpt-5.6-luna` |

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