# KillrVideo 2025 Documentation
> A reference application for DataStax Astra DB
> https://killrvideo.github.io

## Overview
- [Architecture & Vision](/overview/): KillrVideo 2025 architecture overview
- [Technology Stack](/overview/tech-stack/): Technologies used in KillrVideo 2025
- [How Services Connect](/overview/how-services-connect/): Service interaction patterns in KillrVideo

## Getting Started
- [Prerequisites & Setup](/getting-started/): What you need before running KillrVideo
- [Run the Application](/getting-started/run-the-app/): Clone, configure, and run KillrVideo locally
- [Your First API Call](/getting-started/first-api-call/): Register a user and make an authenticated request

## Concepts
- [Data Modeling](/concepts/data-modeling/): Cassandra and Astra DB data modeling primer
- [Authentication & Authorization](/concepts/authentication/): JWT authentication and role-based access control
- [API Patterns](/concepts/api-patterns/): REST conventions, pagination, and error handling
- [Astra Data API](/concepts/data-api/): Working with the Astra DB Data API

## Services

### Account Management
- [Account Management](/services/account-management/): User registration, authentication, and profile management
- [POST /api/v1/users/register](/services/account-management/post-register/): Create a new user account
  - Spec: /services/account-management/_specs/post-register.spec.md
- [POST /api/v1/users/login](/services/account-management/post-login/): Authenticate and receive a JWT token
  - Spec: /services/account-management/_specs/post-login.spec.md
- [GET /api/v1/users/me](/services/account-management/get-me/): Get the current authenticated user's profile
  - Spec: /services/account-management/_specs/get-me.spec.md
- [PUT /api/v1/users/me](/services/account-management/put-me/): Update the current authenticated user's profile
  - Spec: /services/account-management/_specs/put-me.spec.md
- [GET /api/v1/users/{user_id}](/services/account-management/get-user-by-id/): Get public profile information for any user by UUID
  - Spec: /services/account-management/_specs/get-user-by-id.spec.md

### Video Catalog
- [Video Catalog](/services/video-catalog/): Video storage, retrieval, and metadata management
- [GET /api/v1/videos/latest](/services/video-catalog/get-latest/): Retrieve the most recently added videos using time-series data modeling
  - Spec: /services/video-catalog/_specs/get-latest.spec.md
- [POST /api/v1/videos](/services/video-catalog/post-video/): Submit a new video for processing and publication
  - Spec: /services/video-catalog/_specs/post-video.spec.md
- [GET /api/v1/videos/by-tag/{tag_name}](/services/video-catalog/get-by-tag/): Find all videos associated with a specific tag using SAI on a collection column
  - Spec: /services/video-catalog/_specs/get-by-tag.spec.md
- [POST /api/v1/videos/id/{video_id}/view](/services/video-catalog/post-view/): Increment the view counter for a video using Cassandra counters
  - Spec: /services/video-catalog/_specs/post-view.spec.md
- [GET /api/v1/videos/id/{video_id}](/services/video-catalog/get-video-by-id/): Retrieve full video metadata by UUID — the canonical partition key lookup
  - Spec: /services/video-catalog/_specs/get-video-by-id.spec.md
- [PUT /api/v1/videos/id/{video_id}](/services/video-catalog/put-video/): Update video metadata including title, description, and tags with authorization checks
  - Spec: /services/video-catalog/_specs/put-video.spec.md
- [GET /api/v1/videos/id/{video_id}/status](/services/video-catalog/get-video-status/): Lightweight polling endpoint to check video processing status
  - Spec: /services/video-catalog/_specs/get-video-status.spec.md
- [GET /api/v1/videos/by-uploader/{uploader_id}](/services/video-catalog/get-by-uploader/): List all videos uploaded by a specific user using a secondary access pattern
  - Spec: /services/video-catalog/_specs/get-by-uploader.spec.md
- [GET /api/v1/videos/trending](/services/video-catalog/get-trending/): Retrieve trending videos ranked by view count within a configurable time window
  - Spec: /services/video-catalog/_specs/get-trending.spec.md
- [POST /api/v1/videos/id/{video_id}/rating](/services/video-catalog/post-rating/): Submit a 1–5 star rating for a video with upsert semantics
  - Spec: /services/video-catalog/_specs/post-rating.spec.md
- [GET /api/v1/videos/id/{video_id}/rating](/services/video-catalog/get-rating/): Get the average rating and total rating count for a video
  - Spec: /services/video-catalog/_specs/get-rating.spec.md
- [GET /api/v1/videos/id/{video_id}/related](/services/video-catalog/get-related/): Get content-based video recommendations using vector similarity search
  - Spec: /services/video-catalog/_specs/get-related.spec.md
- [POST /api/v1/videos/preview](/services/video-catalog/post-preview/): Validate a YouTube URL and preview metadata before submitting a video
  - Spec: /services/video-catalog/_specs/post-preview.spec.md

### Search
- [Search](/services/search/): Full-text and vector search over the video catalog
- [GET /api/v1/search/videos](/services/search/get-search-videos/): Search videos using semantic or keyword search
  - Spec: /services/search/_specs/get-search-videos.spec.md
- [GET /api/v1/search/tags/suggest](/services/search/get-tags-suggest/): Autocomplete tag suggestions using SAI prefix/text search
  - Spec: /services/search/_specs/get-tags-suggest.spec.md

### Comments & Ratings
- [Comments & Ratings](/services/comments-ratings/): User comments and star ratings on videos
- [POST /api/v1/videos/{video_id}/comments](/services/comments-ratings/post-comment/): Add a comment to a video
  - Spec: /services/comments-ratings/_specs/post-comment.spec.md
- [GET /api/v1/videos/{video_id}/comments](/services/comments-ratings/get-video-comments/): Retrieve paginated comments for a video
  - Spec: /services/comments-ratings/_specs/get-video-comments.spec.md
- [GET /api/v1/users/{user_id}/comments](/services/comments-ratings/get-user-comments/): Retrieve paginated comments made by a specific user
  - Spec: /services/comments-ratings/_specs/get-user-comments.spec.md
- [POST /api/v1/videos/{video_id}/ratings](/services/comments-ratings/post-rating/): Submit or update a rating for a video
  - Spec: /services/comments-ratings/_specs/post-rating.spec.md
- [GET /api/v1/videos/{video_id}/ratings](/services/comments-ratings/get-ratings/): Get the aggregate rating for a video, with optional user-specific rating
  - Spec: /services/comments-ratings/_specs/get-ratings.spec.md

### Recommendations
- [Recommendations](/services/recommendations/): Personalized video recommendations powered by vector similarity
- [GET /api/v1/recommendations/foryou](/services/recommendations/get-for-you/): Get personalized video recommendations for the authenticated user
  - Spec: /services/recommendations/_specs/get-for-you.spec.md
- [POST /api/v1/reco/ingest](/services/recommendations/post-ingest/): Ingest a video embedding vector for recommendation use
  - Spec: /services/recommendations/_specs/post-ingest.spec.md
- [GET /api/v1/videos/{video_id}/related](/services/recommendations/get-related/): Get videos related to a specific video using content similarity
  - Spec: /services/recommendations/_specs/get-related.spec.md

### Moderation
- [Moderation](/services/moderation/): Content flagging, moderation queues, and moderator management
- [POST /api/v1/flags](/services/moderation/post-flag/): Submit a content flag for moderator review
  - Spec: /services/moderation/_specs/post-flag.spec.md
- [GET /api/v1/moderation/flags](/services/moderation/get-flags/): Retrieve the moderation queue, optionally filtered by flag status
  - Spec: /services/moderation/_specs/get-flags.spec.md
- [POST /api/v1/moderation/flags/{flag_id}/action](/services/moderation/post-flag-action/): Take moderator action on a flagged item, updating its status and adding notes
  - Spec: /services/moderation/_specs/post-flag-action.spec.md
- [GET /api/v1/moderation/flags/{flag_id}](/services/moderation/get-flag-details/): Retrieve full details for a specific content flag
  - Spec: /services/moderation/_specs/get-flag-details.spec.md
- [GET /api/v1/moderation/users](/services/moderation/get-users/): Search and list users for moderation purposes
  - Spec: /services/moderation/_specs/get-users.spec.md
- [POST /api/v1/moderation/users/{user_id}/assign-moderator](/services/moderation/post-assign-moderator/): Grant moderator role to a user
  - Spec: /services/moderation/_specs/post-assign-moderator.spec.md
- [POST /api/v1/moderation/users/{user_id}/revoke-moderator](/services/moderation/post-revoke-moderator/): Revoke moderator role from a user
  - Spec: /services/moderation/_specs/post-revoke-moderator.spec.md
- [POST /api/v1/moderation/videos/{video_id}/restore](/services/moderation/post-restore-video/): Restore a previously removed video by clearing its deleted flag
  - Spec: /services/moderation/_specs/post-restore-video.spec.md
- [POST /api/v1/moderation/comments/{comment_id}/restore](/services/moderation/post-restore-comment/): Restore a previously removed comment by clearing its deleted flag
  - Spec: /services/moderation/_specs/post-restore-comment.spec.md

## Advanced Topics
- [Vector Search Deep Dive](/advanced/vector-search-deep-dive/): How KillrVideo uses Astra DB vector search for semantic video recommendations — covering embeddings, NVIDIA NV-Embed-QA, cosine similarity, ANN search, and SAI vector indexes
- [BM25 Full-Text Search Roadmap](/advanced/bm25-roadmap/): How to add BM25 full-text search to Astra DB
- [Deployment Patterns](/advanced/deployment-patterns/): How to deploy KillrVideo locally and in production — local dev with uvicorn, Docker, cloud environments, and Astra DB connection configuration