Here is what we shipped in November 2025

feat(navigation): add TV link to Navbar and update TV page layout

• Why: To enhance user navigation by providing quick access to the TV section, ensuring that users can easily find more content on the platform.

• What:

  • Added a "TV" link to the Navbar for both desktop and mobile views.
  • Updated the TV page layout to include a footer and adjusted styling for better readability, particularly for text colors in the absence of videos.

• How:

  • Modified Navbar.tsx to include a new Link component for the "TV" section, ensuring proper styling and visibility across different screen sizes.
  • Refactored tv.tsx to introduce a footer and restructure the content area, including changes to text color for improved contrast and legibility.
  • Removed the obsolete pages/_document.js file and ensured that the main document structure is preserved in pages/_document.tsx with appropriate attributes.

feat(controllers): refactor request handling and update imports

• Why: The existing controllers were utilizing an outdated request and response model that did not align with the new structure of the application. This refactor improves the clarity and consistency of the codebase by aligning with the updated HttpRequest and HttpResponse classes.

• What:

  • Updated GetMagnetronTvDocumentsController, GetShowcasePendingDocumentsController, and UpdateShowcaseStatusController to import HttpRequest and HttpResponse from the correct path.
  • Modified the executeImpl method in GetMagnetronTvDocumentsController to handle locale and revised error handling to be more general and flexible.
  • Ensured user serialization in UpdateShowcaseStatusController to maintain consistent data processing.

• How:

  • The refactor involved adjusting import paths to correctly reference HttpRequest and HttpResponse while also making internal changes to accommodate the new request handling structure.
  • In GetMagnetronTvDocumentsController, added locale as a query parameter and adjusted the error handling mechanism to eliminate type casting and improve clarity.
  • The serialization of the user object in UpdateShowcaseStatusController enhances data integrity by ensuring the user information is properly formatted before being processed.

This commit ensures that the controllers are more aligned with the evolving architecture of the application while improving maintainability and readability.

feat(sitemap): integrate TV documents into sitemap generation

• Why: To enhance the SEO performance of our application, it's essential to include TV video URLs in the sitemap. This will improve discoverability and indexing of our video content by search engines.

• What: The GenerateSitemapUseCase has been updated to fetch approved TV documents and include their URLs in the generated sitemap. This adds relevant dynamic content alongside static pages.

• How: A new dependency on GetMagnetronTvDocumentsUseCase was introduced to retrieve up to 1000 approved TV documents. The execution of this use case collects video URLs, which are then formatted and appended to the sitemap XML structure. The updated URLs include the last modification date derived from the documents' metadata, ensuring freshness and relevance for search engines.

feat(seo): enhance metadata for better discoverability and sharing

• Why: To improve search engine optimization (SEO) and enhance user engagement through social media sharing, it is crucial to have comprehensive and properly structured metadata on the video and TV pages.

• What:

  • Updated the title and description meta tags for the Magnetron TV page to better reflect content and promote educational videos.
  • Added Open Graph and Twitter Card tags to improve how content is displayed on social media platforms.
  • Implemented JSON-LD structured data for both the TV and individual video pages to enhance search engine indexing and display rich snippets.
  • Created a custom _document.tsx to accommodate locale-specific metadata in the HTML document structure.

• How:

  • The metadata changes in tv.tsx include a more descriptive page title and a dynamic description that incorporates the total number of videos available.
  • For the video pages ([...params].tsx), the metadata now includes dynamic titles and descriptions based on the document's properties, ensuring relevant and concise information is presented.
  • Used dangerouslySetInnerHTML to inject structured data in JSON-LD format, which describes the video gallery and individual videos, improving indexing by search engines.
  • The new _document.tsx allows extraction of locale information from the URL, enabling better localization support for metadata across different regions.

feat(admin): implement showcase status management and pending documents

• Why: To enhance the admin interface for managing showcase statuses of documents, providing a way to review, approve, or reject documents that require showcase status updates.

• What:

  • Added functionality to update showcase statuses of documents.
  • Introduced a new admin page to display documents pending showcase approval.
  • Implemented necessary controllers, use cases, and API routes to handle the fetching and updating of showcase statuses.

• How:

  • Modified the BrowserApiClient to include methods for updating and fetching showcase statuses.
  • Created the GetShowcasePendingDocumentsController to handle the retrieval of documents with a pending showcase status.
  • Developed the UpdateShowcaseStatusController to facilitate status updates.
  • Implemented corresponding use cases for GetShowcasePendingDocumentsUseCase and UpdateShowcaseStatusUseCase that encapsulate the business logic.
  • Modified the Prisma schema to accommodate a new showcaseStatus field for MagnetronDocument and added migration scripts.
  • Developed a new React component to list documents with pending showcase approvals, along with buttons to approve or reject them.

This update allows administrators to effectively manage the showcase status workflow in the Magnetron application, improving content management efficiency.

feat(tv): implement video player page for Magnetron TV documents

• Why: Users need a dedicated video player page to playback content directly from Magnetron TV documents. This feature enhances user experience by allowing seamless navigation to video playback.

• What: Added a new dynamic route for video player pages, implementing logic to fetch and display individual video documents. Updated the Magnetron TV document listing to navigate to corresponding video player pages.

• How:

  • Created a new file at pages/[locale]/tv/[...params].tsx which handles the video playback functionality, including error handling and loading states.
  • Modified the existing document structure in pages/[locale]/tv.tsx to implement the handleCardClick function that utilizes the Next.js router for navigation to the video player page.
  • Enhanced GetMagnetronTvDocumentsUseCase to build a player URL based on the document ID and title, ensuring proper formats using base36 encoding.
  • Updated interfaces in IMagnetronTvDocumentsRequest and IMagnetronTvDocumentsResponse to support the new routing structure and player URLs.
  • Improved the repository methods in MagnetronDocumentRepo to retrieve video documents, ensuring that they are properly fetched based on their unique IDs.

feat(tv): add Magnetron TV documents feature and related components

• Why: To enhance the platform by allowing users to explore videos on a dedicated TV section, thereby improving content discoverability and user engagement.

• What: Introduced a new feature that includes:

  • A new MagnetronTv page for displaying videos.
  • Components to handle document retrieval and presentation, including a dedicated controller, use case, and repository methods for fetching documents with completed versions.
  • Updated the navbar component to reflect the new section, maintaining branding consistency.

• How:

  • Implemented GetMagnetronTvDocumentsController to manage the request lifecycle and interact with the use case that retrieves the videos.
  • Created GetMagnetronTvDocumentsUseCase to encapsulate the business logic for fetching magnetron documents, ensuring appropriate error handling and data fetching strategies.
  • Added a new API endpoint in mainRouter to support TV document retrieval requests.
  • Modified the MagnetronDocumentRepo to facilitate querying documents with completed versions.
  • Enhanced the frontend with necessary components, utilizing React's state management to dynamically display data from the newly created tv.tsx page.

cleanup

cleanup

feat(render): add audio generation from narration in SceneUrlRenderService

• Why: The existing implementation only considers audio URLs present in the scene properties. It does not cater to scenarios where the audio should be generated from text narration, which is essential for scenes lacking pre-defined audio files.

• What: This update introduces checks for the presence of narration and voice settings in the audio properties of the scene. If the audio URL is absent, the service now generates audio using the Chirp3TextToSpeechUseCase.

• How: The code first verifies the existence of the audio field, narration, and voice properties. If any required element is missing, a corresponding failure result is returned. If all necessary components are present but the audio URL is missing, it invokes the TTS use case to create an audio file, handles potential errors during the generation process, and logs the audio generation success with the URL. The implementation leverages async/await for executing the TTS and downloads the resulting audio file to the specified path.

feat(render): preserve intermediate files and videos in non-production

• Why: To facilitate debugging during development and testing, it is essential to retain intermediate video files and frames instead of cleaning them up immediately in non-production environments.

• What: The changes modify the MagnetronVideoRenderService and RenderMagnetronDocumentUseCase classes to conditionally clean up temporary files and local video files based on the environment. In production, files are cleaned up as before, while in non-production environments, relevant messages are logged to indicate that files are being preserved for debugging.

• How:

  • In MagnetronVideoRenderService, the cleanup of intermediate scene videos and frames is wrapped in a conditional check for the NODE_ENV environment variable. If it is not production, the files are preserved, and a message is logged.
  • The method cleanupIntermediateFiles now also includes this environment check to avoid unnecessary deletions in non-production contexts.
  • In RenderMagnetronDocumentUseCase, the local video file cleanup logic similarly checks the environment before proceeding, ensuring local files are only deleted in production. This behavior is communicated to the developer through console logs.

feat(oauth): remove YouTubeOAuthController for streamlining auth flow

• Why: The YouTubeOAuthController was deemed unnecessary for the current authentication architecture. With improvements and refinements in our OAuth handling, this controller added complexity without significant benefits.

• What: The file YouTubeOAuthController.ts has been deleted. This includes all associated methods for authorizing with YouTube, handling OAuth callbacks, and managing refresh tokens.

• How: Removed all code related to OAuth operations for YouTube, including the authorize, callback, and getAccessToken methods. This change simplifies the codebase and encourages a more modular approach to authentication, potentially allowing for better maintenance and clearer separation of concerns in the future.

feat(docker): add service for publishing to YouTube

• Why Introduced support for a dedicated service to manage the YouTube publishing process. This aims to streamline workflows and provide a clear separation between application functionalities.

• What Added a new service definition in the docker-compose.yml file named publish-to-youtube. This service is configured to run the npm run publish-to-youtube command under production settings and uses the existing magnetron-data volume for data persistence.

• How The new service includes specific configuration options such as the build context and Dockerfile specification. The environment variable NODE_ENV is set to production to ensure the correct environment is used during execution. The service is also set to restart unless stopped to improve resilience during runtime.

feat(youtube): enhance video description hashtags in publish workflow

• Why: The previous set of hashtags in the video description lacked coverage for relevant terms that could improve discoverability and searchability on YouTube.

• What: Updated the video description to include new hashtags. Removed "#VideoMarketing" and replaced it with "#Sketch" and "#Whiteboard" to better align with current content themes.

• How: Modified the string concatenation in the getVideoDescription function of the PublishToYoutubeUseCase class. This change directly impacts the metadata exposed to users and algorithms on YouTube, potentially improving the reach of the published videos.

feat(youtube): improve document version handling in publish workflow

• Why: Previously, there was no mechanism to ensure that the YouTube publishing job was executed based on the latest completed document version. This could lead to inconsistencies and unexpected behavior when publishing, especially if multiple versions of a document existed.

• What:

  • Enhanced the PublishToYoutubeController to fetch the latest completed document version before generating the idempotency key.
  • Updated the response structure to include the latest document version ID in the API response when a publishing job is queued.
  • Modified the PublishToYoutubeUseCase to include adjustments in logic for handling document states.

• How:

  • Implemented a call to findLatestCompletedVersion in the MagnetronDocumentVersionRepo to retrieve the most recent version of the document prior to processing the request.
  • Added error handling to manage scenarios where no completed version exists, ensuring that the client receives actionable feedback.
  • Altered the key generation for the idempotency key to incorporate the unique entity ID of the latest version. This change ensures that repeated publish requests for the same document yield unique keys when versions differ.

feat(youtube): add unpublished magnetron documents management UI

• Why: To enhance the management of unpublished magnetron documents, enabling users to view documents that are pending publication and perform actions such as publishing to YouTube directly from the interface.

• What: This update introduces a new UI page for "Unpublished Magnetron Documents" which displays a list of unpublished documents along with their associated metadata. Users can initiate the publishing process to YouTube directly from this page. Additionally, it adds backend support for fetching unpublished documents using a dedicated controller and use case.

• How:

  • Implemented a new React component at pages/admin/magnetron/unpublished.tsx to render the document list with pagination and action buttons.
  • Added GetUnpublishedMagnetronDocumentsController and PublishToYoutubeController to manage the fetching and publishing processes.
  • Enhanced the MagnetronDocumentRepo and its related repositories to fetch documents based on their publication status and count completed document versions.
  • Updated the adminRouter to include new routes for document management features.
  • Adjusted the BrowserApiClient to include methods for interacting with the new backend endpoints.
  • Modified the package.json to reflect the changes in command execution for publishing videos.

feat(youtube): improve video description formatting in publication

• Why: The previous implementation concatenated narrations with a space, which can make the video description less readable and visually cluttered. A clearer format can enhance the viewer's understanding and engagement.

• What: Updated the way narrations are joined to use line breaks instead of spaces. This change allows for better separation of thoughts and improves the overall presentation of the video description.

• How: Modified the narrations.join(" ") line to narrations.join("\n\n"), thereby introducing double line breaks between each narration. This change enhances the readability of the description format in the published YouTube videos.

feat(youtube): enhance YouTube integration with video management capabilities

• Why: Users need a more robust way to manage YouTube videos, specifically to allow for updating existing videos and deleting old videos during the publishing process. This improves the overall user experience and ensures content remains up to date.

• What:

  • Updated the OAuth scopes to use youtube.force-ssl for broader permissions, including uploading, updating, and deleting videos.
  • Implemented video deletion functionality in the YouTubeUploadService, allowing for the removal of old videos when new ones are published.
  • Enhanced the PublishToYoutubeUseCase to check for already published videos and update them if necessary, rather than duplicating content.
  • Added detailed logging around YouTube API interactions, especially in error scenarios, to improve troubleshooting capabilities.
  • Expanded documentation to include information on using the new OAuth scope and the implications for existing setups.

• How:

  • The scope change was made in .envprod and reflected in the setupYoutubeAuth.ts script.
  • New methods in YouTubeUploadService handle the deletion of videos and better error handling for insufficient permissions.
  • The PublishToYoutubeUseCase was modified to generate descriptions dynamically from document narrations and conditionally update YouTube videos based on their publication status.
  • Updated relevant documentation files to guide users through the setup process, including necessary changes due to the broader OAuth scope permissions.

This commit significantly enhances the YouTube integration within the application, ensuring users can effectively manage their video content.

feat(youtube): enhance YouTube integration with OAuth and publish flow

• Why: To streamline the process of uploading videos to YouTube by implementing OAuth 2.0 authentication and integrating it into the existing upload service. This improves security and user experience by enabling automatic token management.

• What:

  • Added a new script setupYoutubeAuth.ts for managing OAuth credentials and obtaining refresh tokens.
  • Created YouTubeOAuthController to handle authorization and callback logic for OAuth.
  • Updated the PublishToYoutubeUseCase to utilize the new OAuth flow, including handling document statuses during the upload process.
  • Introduced new public fields in the database for MagnetronDocument and Contact to track YouTube upload statuses.
  • Developed a dedicated runner PublishToYoutube.ts for command line access to the publish functionality.

• How:

  • Environment variables have been organized, including new additions for OAuth setup.
  • Token management has been refactored to generate and store refresh tokens securely.
  • Enhanced error handling to manage document states effectively during the upload process, ensuring failures are logged but do not block overall functionality.
  • Created migration scripts to modify the database structure to support public links and statuses for documents.
  • Explicit checks are included to ensure proper permission handling before uploads, improving robustness in varying deployment environments.

feat(youtube): implement video upload functionality to YouTube

• Why: To enable users to publish videos generated from Magnetron documents directly to their YouTube channels, enhancing the platform's usability and integration with popular services.

• What: Added a new service, YouTubeUploadService, responsible for handling video uploads to YouTube. Introduced interfaces for requests and responses specific to YouTube publishing. Implemented PublishToYoutubeUseCase to handle the business logic of fetching document versions and facilitating the upload process.

• How:

  • The MagnetronDocumentVersionRepo now includes a method to find the latest completed version of a document.
  • The YouTubeUploadService leverages Google APIs to download video streams and upload them, also managing thumbnail uploads.
  • The PublishToYoutubeUseCase orchestrates the process, validating input and invoking the upload service with necessary data such as video URL and user access tokens.
  • Error handling is implemented to provide meaningful feedback during the upload process.

refactor(MagnetronLoader): remove illustration grid logic for clarity

• Why: The existing approach for handling illustrations was complex and added unnecessary clutter to the MagnetronLoader component. Simplifying this logic will enhance maintainability and readability.

• What: Removed the getIllustrations function and the corresponding IllustrationGrid component that were responsible for rendering a 3x3 grid of illustrations from the magnetron document.

• How: The deletion of both the illustration fetching logic and the grid rendering allows for a cleaner component structure. This change will pave the way for future enhancements regarding how illustrations are managed without impacting performance or functionality. The loading experience remains unchanged as the visual component for illustrations during processing is no longer displayed.