# Learningvideos

Learningvideos is a Django and Django REST Framework service for managing and serving Merchmix Learning Center video content. It provides authenticated CRUD APIs for learning videos, category and text filtering, thumbnail fallback generation for YouTube videos, a Django admin interface, and a public health endpoint. The service stores video metadata and uploaded thumbnails in PostgreSQL-backed Django models and is deployed as a containerized web application.

## Business Summary

This service gives Merchmix users a Learning Center where they can find short training videos about merchandise planning topics such as Allocation, WSSI, Replenishment, and Analytics. Staff can create, update, search, categorize, and remove learning videos, while users can retrieve the content and its thumbnail for display in the learning experience.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Learning Content Management | Other | `production` | `write` | user_facing, agent_facing |
| Learning Content Discovery | Reporting | `production` | `read` | user_facing, agent_facing |
| Learning Video Presentation | Other | `production` | `read` | user_facing |
| Service Health Monitoring | Other | `production` | `read` | agent_facing, internal |
| Learning Center Authorization | Authentication | `partial` | `execute` | user_facing, internal |

**Learning Content Management** — Maintain the training videos available in the Merchmix Learning Center, including their titles, descriptions, video links, durations, categories, thumbnails, and publication metadata.

**Learning Content Discovery** — Allow Merchmix users to browse training videos and narrow results by merchandise-planning category or by words in the title and description.

**Learning Video Presentation** — Provide the information needed for the Learning Center to display a video card, including a usable thumbnail, duration, category, view count, and publication date.

**Service Health Monitoring** — Let deployment and monitoring systems confirm that the Learning Video API is running.

**Learning Center Authorization** — Restrict Learning Center content operations to tenants and users who are entitled to the learning service and have the required action permission.

## Workflows

**Browse and filter learning videos** — A Learning Center client retrieves available training videos and optionally filters them for a category or search term.

1. Send an authenticated GET request to /api/learning/videos/.
2. Optionally provide category and/or search query parameters.
3. The service queries LearningVideo records ordered by most recently updated.
4. The serializer returns video metadata, API-friendly field names, and an uploaded or derived thumbnail URL.

**Create or maintain learning content** — An authorized content administrator maintains the Learning Center catalogue.

1. Authenticate through the MerchMix authorization context.
2. Submit create, update, partial update, or delete requests to /api/learning/videos/.
3. The permission layer checks the learning service entitlement and action-specific permission.
4. Django REST Framework validates and persists the LearningVideo record and any thumbnail upload.

**Resolve a video thumbnail** — The API ensures a video card has a usable poster image where possible.

1. Check whether the LearningVideo has an uploaded thumbnail.
2. Verify that the referenced stored file still exists.
3. Return an absolute media URL when the upload exists.
4. Otherwise extract an 11-character YouTube video ID and return the YouTube hqdefault thumbnail URL; return an empty value for unsupported URLs.

## Architecture

A conventional Django monolith exposes server-rendered administration and REST API endpoints around a single LearningVideo domain model. Authentication is implemented as a custom DRF authentication class that forwards bearer-token context validation to the MerchMix Auth Service, while deployment runs the WSGI application behind Gunicorn in a container.

**Components:** learningvideo Django application and LearningConfig app registration, LearningVideo Django ORM model and initial migration, LearningVideoViewSet and LearningVideoSerializer REST API layer, Custom MerchMix authentication and Learning Center permission policy, Django admin LearningVideo management interface, Django media serving for uploaded thumbnails, Database startup guard enforcing environment-specific PostgreSQL database allowlists, Gunicorn container runtime and Azure/GCP deployment configuration

**Patterns:** Django MVC-style application structure, Django REST Framework ModelViewSet with router-generated CRUD routes, Serializer field mapping from snake_case model fields to frontend camelCase fields, Service-backed authorization context and permission mapping, Environment-driven configuration with fail-closed database-name validation, Fallback external thumbnail generation for YouTube URLs

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `http` | `GET /api/learning/health/` | Public health endpoint returning a JSON success response. |
| `http` | `GET /api/learning/videos/` | List learning videos, optionally filtered with category and search query parameters. |
| `http` | `POST /api/learning/videos/` | Create a learning video, subject to authorization and serializer/model validation. |
| `http` | `GET /api/learning/videos/{id}/` | Retrieve one learning video. |
| `http` | `PUT /api/learning/videos/{id}/` | Replace one learning video. |
| `http` | `PATCH /api/learning/videos/{id}/` | Partially update one learning video. |
| `http` | `DELETE /api/learning/videos/{id}/` | Delete one learning video. |
| `http` | `GET /admin/` | Django admin interface for managing LearningVideo records. |
| `http` | `GET /media/{path}` | Serve uploaded media files, including learning video thumbnails, through Django. |

## Screens

| Route | Name | Purpose |
|---|---|---|
| `/admin/` | Learning Video Admin | Administrative interface for listing, searching, filtering, and editing learning video records. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| LearningVideo | `owns` | Learning content metadata: title, description, video URL, optional thumbnail, duration, category, view count, publication date, and update timestamp. |
| Learning video thumbnail files | `owns` | Optional uploaded image files stored under learning/thumbnails/ and served through the configured media path. |
| Authorization context | `reads` | User, tenant, entitlement, role, group, and permission context supplied by the MerchMix Auth Service for protected API requests. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL | `database` | `reads` | `critical` |
| Django ORM and migration system | `library` | `uses` | `critical` |
| MerchMix Auth Service | `internal_service` | `calls` | `required` |
| merchmix_authlib | `library` | `uses` | `required` |
| YouTube thumbnail service | `external_service` | `reads` | `optional` |
| Redis | `database` | `depends_on` | `supporting` |
| NATS | `queue` | `depends_on` | `supporting` |
| Django REST Framework | `library` | `uses` | `critical` |
| Pillow | `library` | `uses` | `required` |

## Technology

Python 3.12 runtime, Django 6.0.6, Django REST Framework 3.17.1, PostgreSQL via psycopg2-binary, Gunicorn, PyJWT and cryptography, django-cors-headers, WhiteNoise, Pillow, Docker, Azure Container Apps and Google Cloud Run deployment configurations

## Limitations

- The supplied source shows a commented-out increment_view action, so view-count tracking is not currently exposed as an API operation; the views field exists but the evidence does not show it being updated.
- The merchmix_authlib package is conditionally imported and comments state that deployments without it allow authentication and permission checks to become no-ops; authorization enforcement therefore depends on the runtime package being available.
- No frontend implementation is present in this repository; the Learning Center user interface is inferred only from serializer naming and thumbnail comments.
- The scanner reports Redis and NATS signals, but the supplied source does not establish how this service uses them or whether they are runtime dependencies.
- Uploaded media is served from the application filesystem, which deployment comments identify as ephemeral; there is no demonstrated blob-storage integration.
- No evidence establishes video hosting, playback, analytics, recommendation, progress tracking, or course/lesson relationships beyond the LearningVideo record.

## Agent Instructions

Use this repository for Learning Center video catalogue operations and training-content retrieval, not for merchandise planning calculations or video playback analytics.

- For browsing content, call GET /api/learning/videos/ and use category or search query parameters when appropriate.
- For a single item, use /api/learning/videos/{id}/; expect videoUrl, publishedDate, and thumbnail in the response.
- Treat POST, PUT, PATCH, and DELETE as authorization-protected content-management operations requiring the corresponding learning service permission.
- Do not assume the views field is current or incrementable through the API; the increment_view endpoint is commented out.
- Health checks may call /api/learning/health/ without authentication.
- When troubleshooting authorization, verify the bearer token, X-Tenant-Client-Id header, Auth Service context endpoint, learning service entitlement, and action-specific permission.
- Do not assume Redis or NATS behavior without inspecting additional source or deployment configuration.
- Uploaded thumbnail URLs may fail if the underlying container file is absent; the serializer attempts a YouTube fallback for YouTube video URLs.

## Source

| Field | Value |
|---|---|
| Repository | `Learningvideos` |
| Branch | `main` |
| Commit | `1b36a73dd16b` |
| Generated by | `gpt-5.6-luna` |

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