System Requirements Document for pasha

1. Introduction

PaashaClips Studio is a fully local, zero-API-key YouTube content-production pipeline for an independent creator operating on one machine. It generates a long-form video and, when enabled and supported locally, automatically derives captioned vertical Shorts from that video.

The system replaces cloud-dependent generation services with a local stack:

• Ollama for content strategy and script generation.
• Sharp for templated thumbnail generation.
• Piper for text-to-speech.
• FFmpeg for media production and clipping.
• faster-whisper for local transcription and word-level caption timing.

The product must remain useful without any cloud account, API key, credit card, paid tier, or YouTube connection. YouTube publishing is an optional final action using one optional free Google Cloud OAuth client.

2. System Overview

PaashaClips Studio is delivered as a local Express dashboard on port 3456, backed by a SQLite3 Database class and a local filesystem workspace including data/videos/. It retains the established agent-oriented pipeline architecture while replacing core cloud dependencies with local execution.

The intended current pipeline is:

1. Content strategy generation.
2. Script generation.
3. Thumbnail generation.
4. Local text-to-speech generation.
5. Long-form video production.
6. Optional Shorts transcription, selection, clipping, and captioning.
7. Persistence of production records and asset metadata.
8. Manual creator approval or rejection.
9. Optional YouTube OAuth connection and publishing only after explicit approval.

The existing codebase architecture must be inspected before implementation. The inspection must verify or report any mismatch with the described architecture:

• Seven original agents:
  • ContentStrategyAgent
  • ScriptWriterAgent
  • ThumbnailDesignerAgent
  • SEOOptimizerAgent
  • ProductionManagementAgent
  • PublishingSchedulingAgent
  • AnalyticsOptimizationAgent
• SQLite3-backed Database class.
• CredentialManager.
• Express dashboard on port 3456.
• Existing DailyAutomation scheduler.
• Duplicate OAuth flows in modern-auth.js and oauth-server.js.

The current delivery is intentionally constrained to one creator-operated channel and one manual generation trigger. Automated scheduling and multi-channel support are not current product capabilities.

2a. Product Interpretation and Delivery Boundary

PaashaClips Studio is a local-first creator-production utility, not a cloud SaaS service. The Solo Creator / Operator can generate, inspect, approve, reject, and manually upload locally produced assets without ever connecting to Google or supplying an API key.

The system owns the local dashboard, locally stored generated media, review statuses, production metadata, setup checks, and local pipeline execution. The application establishes local first-use enrollment and requires returning verification before protected generated media and review state are available. This identity boundary exists only to preserve ownership and continuity of locally durable creator work; it does not imply account-management, multi-user collaboration, invitations, role-based permissions, or cloud identity features.

YouTube is externally owned. The operator may choose to connect YouTube using one free Google Cloud OAuth client. This connection is separate from generation and review, is optional, and must never block local generation, asset review, approval, or manual upload from data/videos/.

Current delivery excludes:

• Required API keys in the core pipeline.
• Credit-card, paid-tier, or paid-provider dependency in the core pipeline.
• Cloud LLM, cloud image generation, and cloud TTS services in the core pipeline.
• Required YouTube OAuth connection.
• Automatic publishing without explicit approval.
• A separate review queue page.
• Elaborate review-state workflows beyond pending review, approved, and rejected.
• Automation scheduling in the current product workflow.
• Multi-channel support.
• Any API-key prompt during setup unless the operator elects to connect YouTube.

2b. Source Content Inventory

The authoritative existing-artifact source must be read before implementation and used for factual verification, architecture alignment, and implementation patterns.

Verified source-content targets to inspect and preserve where applicable:

• index.js
  • Application startup flow.
  • Express dashboard configuration.
  • Existing dashboard behavior.
  • generateContent() orchestration.
  • logCapabilitySummary().
  • Console startup banner.
  • Existing scheduler startup behavior.
• agents/
  • Existing agent constructor and initialization patterns.
  • Existing content, script, thumbnail, SEO, production, publishing/scheduling, and analytics agent responsibilities.
• database/db.js
  • SQLite3 Database class.
  • Existing persistence methods.
  • saveProductionData.
• utils/credential-manager.js
  • Existing credential ownership and access behavior.
• utils/ffmpeg.js
  • Existing checkFFmpeg() capability-check style and failure messaging.
• modern-auth.js
  • OAuth implementation and auto-browser-open user experience to retain.
• oauth-server.js
  • Duplicate OAuth flow to consolidate and remove.
• test.js
  • Existing SystemTest style.
  • Existing 12 system tests.
  • Simulation-fallback behavior expectations.
• setup.js and walkthrough.js
  • Existing setup flow and capability-check tone.
• README and CONTRIBUTING.md
  • Existing user-facing documentation references and setup instructions.
• package.json
  • Existing scripts, dependencies, user-facing description, and internal package name behavior.

No unverified product facts, populated source collections, contacts, dates, links, or media assets are introduced by this document.

2c. Page Content and Component Coverage

Landing

• Purpose and access
  • Public application entry surface.
  • Available without login to the Solo Creator / Operator and Setup / Installer.
  • Explains that PaashaClips Studio is a fully local, zero-API-key YouTube production pipeline that can create long-form videos and Shorts.
• Information and state
  • Local-first product explanation.
  • Clear statement that core generation requires no paid API key, credit card, paid tier, or cloud account.
  • Clear statement that YouTube connection is optional.
  • Entry-state indication that protected generated assets and review statuses require login.
• Primary actions
  • Continue to Login.
  • Continue to local setup guidance when the visitor is preparing the machine.
• Supporting content
  • Local stack overview: Ollama, Piper, FFmpeg, faster-whisper, and Sharp.
  • Plain-language explanation that approved videos remain in data/videos/ for manual upload when YouTube is not connected.
• Loading, empty, success, error, and recovery states
  • Loading: entry information may render while local availability information is being prepared.
  • Success: visitor proceeds to Login or setup.
  • Error/recovery: where local setup has not been completed, the page directs the Setup / Installer to setup guidance rather than requesting API keys.

Login

• Purpose and access
  • Public local identity-access surface.
  • Available without login.
  • Establishes first-use enrollment for the single self-starting Solo Creator / Operator and verifies returning access before protected state is displayed.
• Information and state
  • First-use enrollment state.
  • Returning verification state.
  • Clear distinction between application access and optional YouTube OAuth.
• Primary actions
  • Establish local operator identity on first use.
  • Verify returning operator access.
  • Continue to Dashboard after successful identity establishment or verification.
• Supporting actions
  • Return to Landing.
  • View that YouTube is not required for local production.
• Failure and recovery
  • Failed verification does not expose generated media, production records, or pending-review statuses.
  • The operator receives a clear local recovery path consistent with the implemented local identity mechanism.
  • The Login page must not make optional YouTube OAuth a prerequisite for Dashboard access.

Dashboard

• Purpose and access
  • Protected main workspace for the Solo Creator / Operator.
  • Requires login.
  • Owns the current manual generation, pipeline progress, review, local capability visibility, and optional YouTube connection interactions.
• Production console
  • Prominent single Generate Video Now control.
  • The action triggers /generate.
  • Only one manual generation trigger is provided.
  • The current product supports one channel only.
  • The dashboard does not provide an automated scheduler workflow.
• Live pipeline progress
  • Shows live progress for the required stages in this order:
    1. Strategy
    2. Script
    3. Thumbnail
    4. TTS
    5. Video
    6. Shorts
  • Displays the active, completed, skipped, degraded, or failed state for applicable stages.
  • Provides a run log drawer or equivalent in-page operational detail for a selected pipeline stage.
• Generated asset review section
  • Displays generated long-form video, thumbnail, and generated Shorts in one minimal dashboard section.
  • Shows local asset previews and asset paths where applicable.
  • Shows review status for each reviewable asset:
    • pending_review
    • approved
    • rejected
  • Provides exactly one Approve control and one Reject control per generated video, thumbnail, and Short.
  • Does not introduce a separate queue page or additional review workflow states.
• Approval behavior
  • After production and optional Shorts clipping complete, generated outputs are placed into pending_review.
  • No item may publish without explicit operator approval.
  • Rejection is a visible final review decision within the supported simple review model.
  • Approved local videos remain in data/videos/ for manual upload unless the operator separately chooses optional YouTube connection and publishing.
• Optional YouTube connection section
  • Separate dashboard section titled exactly Connect YouTube (optional).
  • Starts the consolidated OAuth flow only when selected by the operator.
  • Retains the auto-browser-open experience from modern-auth.js.
  • Shows connection success or failure without affecting local-generation usefulness.
  • OAuth success messages, browser HTML, and console output use the PaashaClips Studio name.
• Local capability status
  • Displays availability of Ollama, Piper, FFmpeg, and faster-whisper.
  • Shows local binary or service name, availability, and version when available.
  • Shows plain-English repair instructions only when a capability is unavailable.
  • Clearly distinguishes:
    • Required local production prerequisites.
    • Missing faster-whisper behavior when Shorts clipping is enabled.
    • Optional Shorts behavior when ENABLE_SHORTS_CLIPPING is disabled.
• Data entities
  • Content record.
  • Production record.
  • Long-form video.
  • Thumbnail.
  • Short.
  • Local capability status.
  • Optional YouTube OAuth connection state.
• Loading, empty, success, error, and recovery states
  • Empty: no generated media exists; the Generate Video Now control remains available.
  • Generating: live stage progress and elapsed execution state are shown.
  • Success: the completed video, thumbnail, and available Shorts appear for review.
  • Degraded success: generation completes without Shorts when Shorts clipping is disabled or faster-whisper is unavailable.
  • Error: failed local capability or failed pipeline stage is clearly identified with plain-English repair or retry guidance.
  • Recovery: after resolving a local dependency issue, the operator can start a new manual generation run; no scheduler silently starts or resumes.

3. Functional Requirements

FR-01 — Local-first pipeline

As a Solo Creator / Operator, I should be able to use the core content pipeline entirely on my local machine without an API key, paid tier, credit card, or cloud account, so that I retain control of production and can work without mandatory external services.

• Provenance: explicit.
• Trigger/input: The operator runs setup and uses the local dashboard.
• Access: Login is required before protected dashboard state is available.
• Behavior and observable result:
  • Core generation executes locally.
  • The system does not require cloud LLM, cloud image generation, cloud TTS, paid services, or API keys for core production.
  • Generated media remains locally available, including in data/videos/.
• Failure/recovery: Missing local dependencies must be reported clearly with install instructions rather than failing silently.
• Continuation: The operator can resolve prerequisites and continue using the local pipeline.

FR-02 — Architecture verification before implementation

As a Setup / Installer, I should have the existing codebase architecture verified before changes are made, so that implementation follows the actual repository rather than assumptions.

• Provenance: explicit.
• Trigger/input: Work begins on the rebrand and pipeline changes.
• Behavior and observable result:
  • The implementation process reads index.js, agents/, database/db.js, utils/credential-manager.js, and utils/ffmpeg.js.
  • It verifies the described seven-agent architecture, SQLite3 database, CredentialManager, Express dashboard on port 3456, DailyAutomation scheduler, and duplicate OAuth modules.
  • Any mismatch is reported before proceeding.
• Failure/recovery: A discovered mismatch must be surfaced and reconciled before the affected implementation work continues.
• Continuation: Confirmed repository patterns guide subsequent changes.

FR-03 — Ordered implementation and quality gates

As a Setup / Installer, I should have implementation performed in the requested phase order with test and lint checks after each phase, so that the system changes remain controlled and regressions are visible.

• Provenance: explicit.
• Trigger/input: Completion of each implementation phase.
• Behavior and observable result:
  • Work proceeds through Phases 1 through 7 in order.
  • After each phase, npm test and npm run lint are run.
  • A summary of changes is shown.
  • Work pauses until the user says continue before the next phase begins.
  • One clear commit is created after each phase, with one concern per commit.
• Failure/recovery: Test or lint failures must be addressed before the next phase proceeds.
• Continuation: The next phase begins only after user continuation approval.

FR-04 — Regression and simulation protection

As a Setup / Installer, I should have regression coverage for each new behavior while preserving the existing 12 system tests and simulation fallback, so that the pipeline remains testable even with zero dependencies installed.

• Provenance: explicit.
• Trigger/input: Each new behavior added in Phases 1 through 7.
• Behavior and observable result:
  • A regression test is added in test.js for each new behavior using the existing SystemTest pattern.
  • The existing 12 system tests remain functional.
  • The pipeline remains able to run in simulation-fallback mode with zero dependencies installed for testing.
• Failure/recovery: Missing dependencies in test environments must not cause silent crashes or invalidate the simulation fallback.
• Continuation: The installer can run the test suite and validate behavior without accounts.

FR-05 — Consolidated optional OAuth module

As a Solo Creator / Operator, I should be able to initiate one optional YouTube OAuth connection flow with the existing auto-browser-open experience, so that optional publishing setup is not duplicated or confusing.

• Provenance: explicit.
• Trigger/input: The operator selects Connect YouTube (optional) from Dashboard.
• Access: Login required for Dashboard; Google OAuth is optional.
• Behavior and observable result:
  • modern-auth.js and oauth-server.js are consolidated into one OAuth module.
  • The retained OAuth flow keeps modern-auth.js auto-browser-open UX.
  • The duplicate OAuth flow is removed.
  • Related package scripts and README references are updated.
  • OAuth success HTML and console logs display “PaashaClips Studio.”
• Failure/recovery: OAuth connection failures are shown clearly and do not block local generation, review, approval, or manual upload.
• Continuation: The operator may retry optional connection later or continue fully locally.

FR-06 — Production API key startup warning

As a Setup / Installer, I should receive a loud startup warning when NODE_ENV=production and API_KEY is unset, so that the condition is visible rather than hidden in logger output.

• Provenance: explicit.
• Trigger/input: Application startup in production mode.
• Behavior and observable result:
  • When NODE_ENV=production and API_KEY is unset, the application emits a loud startup warning in addition to, or instead of, logger-only warning behavior.
• Failure/recovery: The warning is clearly visible to the operator at startup.
• Continuation: The system preserves the zero-key core-pipeline boundary; the warning does not redefine a core pipeline API key as required.

FR-07 — FFmpeg scheduler safety

As a Setup / Installer, I should have any scheduler startup refused loudly when FFmpeg is unavailable, so that automated execution cannot proceed silently without required video tooling.

• Provenance: explicit.
• Trigger/input: Startup of any retained or transitional scheduler behavior.
• Behavior and observable result:
  • FFmpeg availability is checked at startup.
  • If FFmpeg is unavailable, the scheduler does not start and the failure is loud.
• Failure/recovery: Plain-English FFmpeg installation or repair guidance is provided.
• Continuation: The installer resolves FFmpeg availability before any scheduler can start.
• Current boundary: The current product workflow does not expose or run an automation scheduler; this requirement preserves safe handling of the existing scheduler during architecture transition.

FR-08 — Local Ollama content strategy and scripting

As a Solo Creator / Operator, I should have content strategy and scripts generated through local Ollama, so that the core ideation and writing stages require no cloud LLM API key.

• Provenance: explicit.
• Trigger/input: The operator starts Generate Video Now.
• Access: Login required.
• Behavior and observable result:
  • ContentStrategyAgent uses a local Ollama instance at http://localhost:11434.
  • ScriptWriterAgent uses a local Ollama instance at http://localhost:11434.
  • The Ollama model is configurable through .env variable OLLAMA_MODEL.
  • Example supported model configuration includes llama3.1:8b.
  • Cloud LLM calls in these agents are replaced.
• Failure/recovery: If Ollama is unavailable, the system provides clear plain-English instructions rather than silently crashing. Simulation fallback remains available for testing.
• Continuation: Once Ollama is available, the pipeline continues from strategy to script.

FR-09 — Local templated thumbnail generation

As a Solo Creator / Operator, I should receive a templated thumbnail made locally with Sharp, so that thumbnail creation makes zero external calls.

• Provenance: explicit.
• Trigger/input: The pipeline reaches the thumbnail stage after strategy and script generation.
• Access: Login required.
• Behavior and observable result:
  • ThumbnailDesignerAgent replaces AI image generation with a Sharp-generated template.
  • The template includes a background and title text overlay.
  • Thumbnail generation makes zero external calls.
  • The generated thumbnail appears with the associated video in the Dashboard review section.
• Failure/recovery: A generation error is shown as a thumbnail-stage failure and allows a subsequent manual run after the local issue is corrected.
• Continuation: A successful thumbnail proceeds to TTS and video production.

FR-10 — Local Piper text-to-speech

As a Solo Creator / Operator, I should have script narration generated through local Piper TTS, so that voice production does not use a cloud TTS provider.

• Provenance: explicit.
• Trigger/input: The pipeline reaches the TTS stage.
• Access: Login required.
• Behavior and observable result:
  • ProductionManagementAgent uses a local Piper TTS call.
  • Cloud TTS providers are not used for this step.
  • The generated narration supports local long-form video production.
• Failure/recovery: If Piper is missing or unavailable, the system presents plain-English installation or repair instructions and does not silently crash.
• Continuation: Once Piper succeeds, the pipeline advances to video generation.

FR-11 — Local capability checks and summary

As a Setup / Installer, I should receive clear local capability checks for Ollama, Piper, FFmpeg, and faster-whisper, so that I can prepare or repair the machine without cloud credential prompts.

• Provenance: explicit and required_inference.
• Trigger/input: Application startup and execution of setup.js or walkthrough.js.
• Behavior and observable result:
  • Ollama availability is checked as a local service availability condition.
  • Piper availability is checked as a local binary availability condition.
  • FFmpeg availability is checked using the existing checkFFmpeg() style.
  • faster-whisper availability is checked for Shorts functionality.
  • logCapabilitySummary() reports the local stack rather than legacy OpenAI, Gemini, ElevenLabs, or Azure checks.
  • setup.js and walkthrough.js report missing capabilities in the established FFmpeg-check tone and provide install instructions.
  • No API key prompt is presented unless the operator chooses optional YouTube connection.
• Failure/recovery: Missing capabilities yield clear, actionable install guidance; failures are never silent.
• Continuation: The installer resolves needed components, or the system uses supported graceful degradation and simulation behavior.

FR-12 — Shorts clipping agent

As a Solo Creator / Operator, I should have the system generate two or three high-hook-potential Shorts from a completed long-form video when Shorts clipping is enabled and locally supported, so that every produced video can also yield vertical short-form clips.

• Provenance: explicit.
• Trigger/input: ProductionManagementAgent completes the long-form .mp4 and ENABLE_SHORTS_CLIPPING=true.
• Access: Login required.
• Behavior and observable result:
  • A new agents/shorts-clipping-agent.js follows the repository’s existing agent pattern.
  • Its constructor accepts db and credentials.
  • It provides initialize().
  • It is invoked by generateContent() after production and before the database-save step.
  • It transcribes the long-form video locally using faster-whisper through a Python subprocess or an appropriate Node binding.
  • It sends the local transcript to Ollama to identify two or three highest-hook-potential segments.
  • It cuts selected segments using FFmpeg into 9:16 vertical clips.
  • It burns word-by-word captions into clips using faster-whisper word-level timestamps.
• Failure/recovery: If faster-whisper is not installed, Shorts clipping degrades gracefully in the same spirit as the FFmpeg check pattern. The long-form pipeline remains usable.
• Continuation: Available Shorts are saved and shown for individual review; unavailable Shorts do not prevent long-form review.

FR-13 — Shorts persistence

As a Solo Creator / Operator, I should have each generated Short persisted with its required metadata and review status, so that I can inspect and approve or reject it independently.

• Provenance: explicit.
• Trigger/input: A Short is successfully created by the Shorts clipping agent.
• Access: Login required to view protected records.
• Behavior and observable result:
  • database/db.js defines a shorts table.
  • Each Short row includes:
    • contentId as a foreign key.
    • path.
    • title.
    • durationSec.
    • status.
  • Supported status values are:
    • pending_review
    • approved
    • rejected
  • saveProductionData inserts generated Short rows.
• Failure/recovery: Failed Short persistence is reported as a production persistence failure and must not be represented as an available reviewable asset.
• Continuation: Persisted Shorts appear in the Dashboard review section.

FR-14 — Feature-flagged graceful Shorts behavior

As a Solo Creator / Operator, I should be able to run the pipeline correctly with Shorts clipping disabled or with faster-whisper unavailable, so that optional clip generation does not make long-form production unusable.

• Provenance: explicit.
• Trigger/input: .env value ENABLE_SHORTS_CLIPPING is not true, or faster-whisper is unavailable.
• Access: Login required for dashboard runs.
• Behavior and observable result:
  • Shorts clipping is enabled only when ENABLE_SHORTS_CLIPPING=true.
  • With the flag off, the long-form pipeline completes without Shorts processing.
  • With faster-whisper unavailable, the pipeline degrades gracefully rather than silently crashing.
  • Dashboard progress communicates the skipped, unavailable, or degraded Shorts result.
• Failure/recovery: The operator receives faster-whisper installation guidance when relevant.
• Continuation: The completed long-form video and thumbnail proceed to pending review.

FR-15 — Pending-review approval gate

As a Solo Creator / Operator, I should have generated production outputs placed in pending_review before any publishing action, so that nothing publishes without my explicit approval.

• Provenance: explicit.
• Trigger/input: Production and optional Shorts clipping complete.
• Access: Login required.
• Behavior and observable result:
  • Generated outputs are assigned pending_review after production and Shorts processing and before any scheduleContent() behavior.
  • No video or Short may publish without explicit operator approval.
  • The approved/rejected decision is controlled by the operator from Dashboard.
• Failure/recovery: A pending item remains unpublished when no decision has been made.
• Continuation: The operator approves for optional publishing or manual upload readiness, or rejects the item.

FR-16 — Minimal per-asset review controls

As a Solo Creator / Operator, I should be able to approve or reject each generated video, thumbnail, and Short from one Dashboard review section, so that review remains direct and lightweight.

• Provenance: explicit.
• Trigger/input: Generated production assets are displayed on Dashboard.
• Access: Login required.
• Behavior and observable result:
  • Each generated video, thumbnail, and Short has one Approve action and one Reject action.
  • The resulting status is visibly updated to approved or rejected.
  • The interface does not add a separate review queue page.
  • The interface does not add elaborate intermediate review states.
• Failure/recovery: If a status update fails, the existing status remains visible and the operator receives an actionable error.
• Continuation: Approved videos remain local for manual upload or optional YouTube publishing; rejected assets remain visibly rejected.

FR-17 — One-click manual generation and live progress

As a Solo Creator / Operator, I should be able to start one video-generation run from a single Generate Video Now button and observe live progress through every stage, so that the local pipeline is understandable and controllable.

• Provenance: explicit.
• Trigger/input: The operator selects Generate Video Now on Dashboard.
• Access: Login required.
• Behavior and observable result:
  • The control triggers /generate.
  • The dashboard displays live progress in this exact sequence:
    1. Strategy
    2. Script
    3. Thumbnail
    4. TTS
    5. Video
    6. Shorts
  • The run produces a long-form video and