diff --git a/Frontend.md b/Frontend.md index 748188aa..a2326a91 100644 --- a/Frontend.md +++ b/Frontend.md @@ -26,7 +26,149 @@ **Your Solution for problem 1:** -You need to put your solution here. +1. Screen Architecture & User Flow + 1.1 Upload Screen + + Core UI: A large "Drag & Drop" zone specifically designed for batching. + + Key Features: + + Folder Picker: Since the requirement mentions "local folder containing many videos," use to allow uploading entire directory structures at once. + + Pre-flight Check: A table listing detected video files with their sizes. This allows users to deselect huge files or unsupported formats before the upload starts. + + Global Progress Bar: Visualizes the aggregate upload status of the batch. + + 1.2 Jobs List + + Layout: A tabular view or card grid sorted by "Last Updated." + + Columns/Data: Video Name, Upload Date, Duration, and a prominent Status Badge (Queued, Processing, Done, Failed). + + Action: Clicking a job row navigates to the Job Detail view. + + 1.3 Job Detail + + Purpose: To give transparency into the "black box" of async processing so users don't abandon the tab. + + UI Components: + + Stepper Component: Visualizes the backend pipeline: Upload → Transcoding → Audio Extraction → AI Summarization → Asset Generation. + + Real-time Logs: A scrolling terminal-like window showing log events (e.g., "Extracting clip 4/10..."). + + Cancel/Retry Controls: Context-sensitive buttons. + + 1.4 Results View + + Layout: A Split-Pane layout. + + Left Pane (Interactive Markdown): Renders the Summary.md. + + Right Pane (Media Player): A video player that loads the full video or individual clips. + + Interaction: + + Click-to-Seek: Timestamps in the Markdown (e.g., [04:23]) are clickable links. When clicked, the media player on the right jumps to that exact second. + + Asset Gallery: A grid section at the bottom for Screenshots and downloadable Clips. + +2. UI States & State Management +Handling long-lived asynchronous jobs requires a granular state machine on the frontend to prevent users from staring at infinite spinners. + + [idle]: Ready to accept files. + + [uploading]: Client is chunking and sending the 200MB+ file to the server/S3. + + [queued]: Upload complete, waiting for a worker node on the backend. + + [processing]: Worker is executing. The UI must reflect active work (e.g., pulsing animations, active log streams). + + [partial_output]: (Crucial for this use case) The Markdown summary is ready, but the heavy video clip cutting is still running. The UI allows the user to read the Summary.md while a banner says "Generating clips...". + + [success]: Fully complete. Shows a CTA to navigate to the Results screen. + + [failed]: Shows a clear error message (e.g., "Corrupted video file") and a Retry button. + + [retry]: Bypasses the upload state (if the file is already in server storage) and jumps straight back to queued. + +3. API Calling Plan + For large files and long-running jobs, standard REST calls will time out. We need a hybrid approach. + + 3.1 Upload Strategy (Chunked Uploads) + Do not send a single 200MB+ POST request. It is fragile. + + Protocol: Use Resumable Uploads (like TUS protocol or AWS S3 Multipart Upload). + + Method: Break the file into 5MB chunks on the client. Send chunks sequentially or in parallel batches. + + Benefit: If the network drops at 99%, we only retry the last chunk, not the whole 4-hour video. + + 3.2 Progress Tracking (SSE vs. Polling) + + Primary Strategy: Server-Sent Events (SSE). + + Open a connection ([/api/jobs/:id/events]). The server pushes updates (logs, status changes) instantly. This is more efficient than polling for a 3-hour job. + + Fallback Strategy: Adaptive Polling. + + If SSE fails (firewall issues), fall back to "exponential backoff polling" (poll every 5s, then 10s, then 30s) to reduce server load. + + 3.3 Abort & Navigation + + AbortController: Attach an [AbortController] signal to the upload fetch request. If the user clicks "Cancel," call [controller.abort()] to kill the network request immediately. + + Navigation: If the user navigates away during an upload, trigger a browser confirm dialog ([window.onbeforeunload]): "Upload in progress. Leaving will cancel the job." + +4. Caching Strategy + We want to minimize network requests while ensuring data isn't stale. I would use TanStack Query (React Query) or SWR. + + 4.1 Jobs List: + + Strategy: [stale-while-revalidate]. + + TTL: Short (e.g., 30 seconds). We want the user to see new jobs reasonably fast, but instant updates aren't critical unless they are on the detail view. + + 4.2 Job Detail (Active): + + Strategy: No Caching / Real-time. Reliance on SSE. If the user leaves and returns, fetch the latest state immediately. + + 4.3 Job Detail (Completed/Results): + + Strategy: Cache Indefinitely (until explicit invalidation). + + TTL: [Infinity] (or 24 hours). Once a job is "Success," the summary and asset links rarely change. + + 4.4 Invalidation Triggers: + + On Upload: Invalidate ['jobs-list']. + + On Delete: Invalidate ['jobs-list'] and remove specific ['job', id] from cache. + +5. Debugging Plan ("Stuck Processing") + When a user claims a video is "stuck," frontend debugging is limited but crucial for triage. + + 5.1 Correlation IDs (The "Trace ID") + + Concept: Generate a unique [client-request-id] (UUID) in the frontend when the upload starts. + + Implementation: Send this header with every request (upload chunks, status checks). + + Display: Show this ID in small gray text in the Job Detail footer (e.g., Ref ID: a1b2-c3d4). The user can copy-paste this to support, allowing engineers to grep backend logs for that specific lifecycle. + + 5.2 Frontend Heartbeat Monitor + + Logic: Implement a client-side timer. If the job status hasn't changed and no new log lines have arrived via SSE for > 15 minutes: + + Action: Auto-trigger a "Health Check" API call. + + UI: If the health check fails or times out, assume the worker died. Transition UI to "System Error" rather than leaving it spinning indefinitely. + + 5.3 Network & Console Observability + + Console Logs: Keep a "Redux-logger" style history in memory. If a crash occurs, we can dump the last 50 state transitions to Sentry/Datadog. + + Network Waterfall: Check if the SSE connection is actually open. Often "stuck" processing is just a closed socket that the UI didn't detect. Implement auto-reconnect logic on the SSE stream. --- @@ -44,8 +186,117 @@ You need to put your solution here. **Your Solution for problem 2:** -You need to put your solution here. +1. Screen Architecture & User Flow + This flow needs to feel like a cohesive pipeline rather than disconnected pages. + + 1.1 Connect Screen (The Gatekeeper) + + Core UI: A clean, high-conversion landing page. + + Key Feature: A prominent "Connect with LinkedIn" OAuth button. The frontend must handle the OAuth redirect state securely, storing a temporary nonce in [sessionStorage] to prevent CSRF attacks during the redirect flow. + + 1.2 Persona Editor (The Foundation) + + Layout: A multi-section form (potentially a wizard/stepper to avoid cognitive overload). + + Inputs: Background (textarea), Tone (slider or multi-select chips like "Professional", "Witty"), Do's/Don'ts (dynamic list inputs where users can add/remove rules). + + 1.3 Creation Hub: Topic Input & Drafts (The Core Engine) + + Layout: A split view or a sequential flow. Top/Left side takes the "Topic" and "Context". Bottom/Right displays the results. + + The "3 Variants" UI: Once generated, display the posts as three distinct, side-by-side cards (e.g., "The Insight", "The Story", "The Checklist"). + + Interaction: The user clicks a card to "Select" it, which activates the Approval/Scheduler flow. + + 1.4 Approval & Scheduler (The Checkpoint) + + Layout: A modal or slide-over panel over the selected draft. + + Core UI: * A final rich-text editable view of the chosen draft (users always want to make one last tweak). + + Radio buttons: "Post Now" vs. "Schedule for Later". + + Date/Time Picker: Must include a visible Timezone dropdown, defaulting to the user's browser timezone via [Intl.DateTimeFormat().resolvedOptions().timeZone]. + + 1.5 Post History (The Dashboard) + + Layout: A data table or kanban board with tabs: Drafts, Scheduled, Published, Failed. + + Features: Quick actions to "Edit/Reschedule" a queued post, or "View on LinkedIn" for published ones. + +2. Form UX & Guardrails + Persona Validation: Enforce a minimum character count (e.g., 50 chars) on the "Background" textarea. If the user writes "I do sales," the AI cannot generate a good persona. Give visual feedback: "Write a bit more for better AI results." + + Topic Input Rules: Cap the topic input at ~500 characters. If it's too long, the user is essentially writing the post themselves, overriding the persona. + + Scheduling Guardrails: + + No Time Travel: Disable past dates and times dynamically based on the current minute. + + Platform Limits: If LinkedIn only allows scheduling up to 3 months in advance via API, disable dates beyond that in the date picker. + + Timezone Math: Always display time in the UI in the user's selected timezone, but serialize the payload to ISO 8601 UTC before sending it to the backend (new Date(localTime).toISOString()). + +3. API Calling Plan & State Management + 3.1 Draft Generation Lifecycle (Handling LLM Latency) + LLM generation takes time (often 5–15 seconds for 3 variants). + + Do not use a static spinner. Users will think it broke. + + Implementation: Use a sequenced loading state. Cycle through text like "Analyzing your persona..." (0-3s) → "Drafting 'The Story' variant..." (3-7s) → "Polishing 'The Checklist'..." (7-12s). + 3.2 Optimistic UI vs. Strict Confirmation + + Optimistic Updates: Use this for non-destructive actions. If a user deletes a draft from their history, remove it from the UI instantly while the DELETE request happens in the background. + + Strict Confirmation: Use this for publishing. When a user clicks "Schedule", show a spinner. Do not show a success toast until the backend explicitly returns a 200 OK with a scheduled job ID. LinkedIn API failures (like token expiration) are too common to guess. + +4. Caching Strategy (TanStack Query) + Effective caching prevents redundant API calls, handles rate limits, and keeps the UI feeling instant. + + 4.1 Cache Lifecycles (TTL) + + Persona Data (staleTime: Infinity): User preferences rarely change per session. Cache indefinitely to save database reads. + + Drafts (staleTime: 0): Ephemeral. We want fresh LLM generations every time to avoid stale context. + + Post History (staleTime: 1-5 mins): stale-while-revalidate. Displays the cached list instantly while quietly fetching the latest status (e.g., "Scheduled" → "Published") in the background. + + OAuth Status (staleTime: 5 mins): Strict fetch to guarantee token validity just before attempting to publish. + + 4.2 Cache Invalidation (Keeping UI Synced) + + Manual Triggers: When a user clicks "Schedule", immediately call queryClient.invalidateQueries(['postHistory']) to force the dashboard to update. + + Event-Driven: If using Server-Sent Events (SSE) for job completion, intercept the "Job Success" event to invalidate the history cache without requiring a page reload. + + 4.3 Optimistic Updates (Perceived Speed) + + Use Case: Deleting a scheduled post. + + Execution: When clicked, instantly remove the post from the local cache (onMutate) so the UI updates immediately. If the server request fails, roll back to the previous state (onError). Regardless of outcome, refetch the true server state afterward (onSettled). + + 4.4 Prefetching (Zero-Latency Navigation) + + Bind queryClient.prefetchQuery to the onMouseEnter event of navigation links. For example, if the user hovers over "Post History", we fetch the data so the page renders instantly by the time they click. + +5. Debugging Plan (Surfacing Failures) + LinkedIn integration will inevitably fail due to API changes, rate limits, or expired tokens. + + 5.1 Human-Readable Error Mapping + Never show the user Error 401: Token invalid or 429: Rate Limit Exceeded. + + Map backend error codes in the frontend to actionable UI states. + + Example: ERR_LINKEDIN_AUTH → Show a banner: "Your LinkedIn connection expired. Please click here to reconnect." + + 5.2 The "Failed" State in Post History + If a scheduled post fails at the time of publishing: + + Flag it prominently with a red badge in the Post History tab. + + Provide a "Copy Diagnostic Data" button hidden behind an info icon. This copies a JSON string to the clipboard containing the jobId, timestamp, timezone, and the exact error code, making support tickets instantly solvable for your engineering team. --- ## **Problem 3: DOCX Template → Bulk Generator (Frontend System Design)** @@ -62,8 +313,90 @@ You need to put your solution here. **Your Solution for problem 3:** -You need to put your solution here. +1. Screen Architecture & User Flow + The interface must transition smoothly from a setup phase to a high-volume execution phase. + + 1.1 Template Upload & Setup + + Upload Zone: Standard drag-and-drop for the base .docx file. + + Field Review/Editor (Split Screen): * Left Pane: A visual list or extracted view of the detected template tags (e.g., {{FirstName}}, {{Amount}}). + + Right Pane: The Schema Editor. A list where the user defines the data type for each tag to enforce strict validation rules. + + 1.2 The Execution Hub (Tabs: Single vs. Bulk) + + Single Fill Form: A dynamic, auto-generated web form based on the schema defined in the setup step. + + Bulk Upload: A dedicated dropzone specifically for .csv or .xlsx files, accompanied by a "Download Sample CSV" button generated dynamically from the template schema. + + 1.3 Bulk Mapping & Run Status + + Mapping UI: A two-column interface. Left: Template Fields. Right: Dropdowns containing the uploaded CSV headers. Auto-match these based on string similarity (e.g., matching "EmpName" to "EmployeeName"). + + Run Status Modal: A real-time progress bar (e.g., "Generated 450 / 10,000 documents"). + + 1.4 Report Table & Downloads + + Report View: A paginated data table showing the exact status of the batch job. + + Downloads: A prominent sticky header with primary actions: "Download All (ZIP)" and "Export Error Log (CSV)". + +2. Field UI & Dynamic Form Architecture + Rendering forms with potentially dozens of fields requires strict performance management to prevent keystroke lag. + + Form State Management: Use React Hook Form. It uses uncontrolled components, meaning typing in the "Address" field won't cause the entire form (and its other 40 fields) to re-render. + + Field Types & Inline Validation: + + Integrate Zod for schema validation. Build the Zod schema dynamically on the fly based on the template metadata. + + Text: Standard input, check for empty strings if marked as required. + + Number/Currency: Enforce numeric input, auto-format with commas on blur. + + Date: Provide a native date picker (). Ensure the frontend standardizes the date format (e.g., ISO 8601) before sending it to the backend to ensure the generated PDF renders the date perfectly. + + Defaults: Pre-fill fields if a default value was set in the Field Editor to reduce manual entry time. + +3. Bulk UX (Data & Mapping) +When processing thousands of rows for large-scale awareness campaigns or official beneficiary letters, the frontend must act as a strict validation gate to save server costs. + + Client-Side CSV Parsing: Use a library like PapaParse. Before uploading a 10,000-row CSV to the server, parse it in the browser. + + Pre-flight Checks: Instantly warn the user if the CSV is missing required columns or contains formatting errors (e.g., letters in a "Salary" column) before the batch job starts. + Handling Partial Success: In a batch of 10,000, 50 might fail due to bad data. + + UX: Do not mark the whole job as "Failed." Mark it as "Completed with Errors." + + Actionable UI: Provide a single button to "Download Failed Rows as CSV". The user can fix those specific 50 rows in Excel and drop the file right back into the Bulk Upload screen. + +4. Browser Caching Strategy (TanStack Query) +Managing the state of long-running tabular data requires precise cache control. + + Template Metadata & Field Schema: * Strategy: staleTime: Infinity. Once a template is configured, its schema (fields, required status) does not change unless explicitly edited. Cache this aggressively to keep the UI snappy. + + Bulk Report Pagination: * Strategy: Use TanStack Query's placeholderData: keepPreviousData (formerly keepPreviousData: true). + + UX Benefit: When a user clicks "Page 2" of a 500-page error report, the table will not flash white or show a jarring loading spinner. It keeps Page 1 visible while fetching Page 2 in the background, creating a seamless browsing experience. + + Invalidation: Invalidate the ['bulk-reports', templateId] cache key whenever a new CSV upload completes. + +5. Downloads & Async Handling +Handling massive ZIP file generation and delivery requires careful frontend orchestration. + + Safe Download UX (Pre-signed URLs): * The backend should not send raw binary data for a 500MB ZIP file through the standard API response. + + Instead, the backend returns a short-lived, pre-signed S3 URL (or equivalent). + + The frontend programmatically triggers the download by creating an invisible tag with the href set to the signed URL and the download attribute applied, then calling .click() on it. + + The "Preparing ZIP" State: + + Even after 10,000 PDFs are generated, zipping them on the server takes time. + + When the user clicks "Download ZIP", show a distinct "Zipping files..." loading state based on SSE (Server-Sent Events) or a polling endpoint until the signed URL is ready. --- ## **Problem 4: Character-Based Video Series Generator (Frontend System Design)** @@ -79,7 +412,53 @@ You need to put your solution here. **Your Solution for problem 4:** -You need to put your solution here. +1. Screen Architecture & User Flow +The interface must separate the "World Building" phase from the "Episodic Execution" phase to avoid overwhelming the user. + + 1.1 Character Library (The "Series Bible" Hub) + + Layout: A visual grid of character cards showing their primary reference image, name, and a summary badge of their archetype (e.g., "The Mentor"). + + Interaction: Clicking a card opens a slide-over drawer to edit their detailed traits, visual consistency rules, and voice profiles. + + 1.2 Relationship Editor + + Layout: A visual node-based graph interface (using a library like React Flow). + + Interaction: Characters are nodes. Users can drag connections between them and label the edges (e.g., "Rivals", "Parent-Child"). This creates an intuitive, highly visual map of the series dynamics. + + 1.3 Episode Creator (The Prompt Engine) + + Core UI: A focused creation wizard. + + Steps: 1. Define the story prompt and goal. + 2. Multi-select characters from a visual carousel to "cast" them in the episode. + 3. Configure constraints (duration, tone, aspect ratio). + + 1.4 Episode Detail & Asset Gallery (The Storyboard) + + Layout: A horizontal, scrollable timeline representing the 5-minute episode, broken down into distinct scene blocks. + + Features: Each scene block contains its script snippet, active characters, and generated thumbnail. Below the timeline, a masonry grid serves as the Asset Gallery, housing all generated background prompts, voiceover clips, and character sprites for that specific episode. + +2. Consistency UX (The "Locked State" Problem) +If a user generates an episode on Monday, and then changes a character's eye color in the Library on Tuesday, the Monday episode's metadata must not retroactively break or change. + + Locked Character Profiles: When an episode is generated, the frontend must pass the current state of the selected characters to the backend, which saves a frozen snapshot of those profiles attached to the episodeId. + + Version Badges: In the Episode Detail view, display a subtle badge on the character avatars (e.g., v1.2). If the user clicks it, show a diff or a tooltip: "This episode was generated using an older version of this character." + + Regeneration UX: If a user wants to regenerate an old scene with a newly updated character, provide a clear "Sync to Latest Character Version" action button that explicitly warns them about the change before spending rendering credits. + +3. API Calling & Long-Running Jobs +Generating a 5-minute AI video with distinct characters, audio, and compiled scenes is a massive asynchronous job that could take 10 to 30 minutes. + + The "Hacker Terminal" Progress UI: Instead of a boring, static loading bar for a 20-minute wait, implement an animated, terminal-style log window. Streaming real-time, highly technical-looking updates via Server-Sent Events (SSE)—such as [00:14:02] Compiling visual assets for Scene 3... or [00:14:05] Stitching audio layer...—keeps the user engaged and visually reassures them that the system is actively working hard. + + Resume & Reconnection: If the user closes their laptop and returns an hour later, the frontend must detect the active job upon remounting. Fetch the current job status via a GET request on load. If it is still processing, immediately re-establish the SSE connection using the jobId to resume the live terminal feed. + +4. Caching Strategy (TanStack Query) +Managing the heavy image assets and relational data requires aggressive caching to prevent the app from feeling sluggish. --- @@ -90,29 +469,58 @@ Answer these in **bullet points** (max 1 page total): 1. **Frontend stack choice** * EDIT YOUR ANSWER HERE: Framework (Next.js/Vue/etc), state management, router, UI kit, why. - `` + ` + + ` + + + + 2. **API layer design** * Fetch/Axios choice, typed client generation (OpenAPI), error normalization, retries, request dedupe, abort controllers. ` - ` + + + + + + + ` + + 3. **Browser caching plan** * What you cache (GET responses, derived state), where (memory, IndexedDB, localStorage), TTL/invalidation rules. * How you handle “job status updates” without stale UI. ` - ` + ` + + ` + ` + + + + + 5. **Security basics** * Token storage approach, CSRF considerations (if cookies), XSS avoidance for markdown rendering, safe file download patterns. - ` A` + ` A` + + `CSRF Considerations: Pass cryptographically secure anti-CSRF tokens in the headers for all state-mutating requests, validated by the backend.` + + `XSS Avoidance: Enforce a strict Content Security Policy (CSP). Sanitize all LLM-generated markdown or dynamic HTML using DOMPurify before rendering it into the DOM.` + + `Safe Downloads: Use transient URL.createObjectURL(blob) links for client-generated assets, and short-lived, pre-signed URLs from the backend for heavy assets (ZIPs, final videos) to prevent unauthorized hotlinking.`