diff --git a/Frontend.md b/Frontend.md index 748188aa..bcd69f94 100644 --- a/Frontend.md +++ b/Frontend.md @@ -25,9 +25,62 @@ * **Debugging plan:** how you would debug “stuck processing” from frontend side (network logs, correlation id display) **Your Solution for problem 1:** +### 1. Executive Summary +This document outlines the frontend architecture for a platform that processes large, long-duration videos (200MB+, 3-4 hours) into structured markdown summaries and extracted assets. Given the long-running asynchronous nature of the backend processing, the frontend prioritizes highly resilient upload mechanisms, real-time observability of job status, and an intuitive results viewer. + +### 2. Frontend Tech Selection & Reasoning +* **Core Framework:** React (via Vite) - Unmatched ecosystem for complex interactive UIs. Vite provides near-instant HMR, essential for rapid iteration. +* **Data Fetching & Caching:** TanStack Query (React Query) - Built-in support for polling, caching, background refetching, and error retries. +* **Global Client State:** Zustand - Lightweight global state for ephemeral UI concerns (active upload queues, toast notifications) avoiding Context re-render hell. +* **Routing:** React Router - Industry standard. Enables nested layouts (e.g., Jobs -> JobDetail). +* **Styling & UI Library:** Tailwind CSS + Radix UI - Rapid, consistent styling with accessible primitives for screen-reader-friendly UI. +* **Markdown Rendering:** react-markdown + DOMPurify - Required to safely parse and render the generated Summary.md. + +### 3. UI Architecture & Component Design +**Routing Structure:** +* `/` (Dashboard / Upload) +* `/jobs` (Jobs List) +* `/jobs/:jobId` (Job Detail / Logs) +* `/results/:videoId` (Results Viewer) + +**Key Screens & Reusable Patterns:** +* **Upload Screen:** `` - Drag-and-drop zone. Visual upload queue showing per-file progress, speed, and time remaining. +* **Jobs List:** `` - Paginated list showing Filename, Status Badge, Progress (%), and Time Elapsed. +* **Job Detail (Status/Logs):** `` & `` - A stepper component showing stages. Below it, a terminal-like auto-scrolling log viewer for partial outputs. +* **Results Screen:** ``, ``, `` - Split pane. Left side: Rendered Summary.md. Right side: Original video. Clicking a timestamp seeks the video player automatically. + +### 4. API Calling Strategy & Data Fetching +* **Upload Strategy:** Chunked/Multipart Uploads via the TUS Protocol. If a 500MB upload fails at 99%, chunking allows it to resume rather than restarting. +* **Job Tracking (Polling vs SSE):** Primary strategy is Server-Sent Events (SSE) to `/api/jobs/:jobId/stream`. Server pushes state changes. Fallback is Smart Polling (exponential backoff) via React Query if SSE is blocked. +* **Abort & Cleanup:** Using `AbortController`. When navigating away from `/jobs/:jobId`, the useEffect cleanup invokes `abortController.abort()` to terminate SSE or polling to prevent memory leaks. + +### 5. UX Quality for Async Jobs & State Management +* **QUEUED:** Show estimated time/position in queue. +* **PROCESSING:** Show granular progress text ("Generating summary (stage 3/5)..."). +* **PARTIAL_OUTPUT:** Stream raw transcripts to UI early while video encodes in background. +* **FAILED:** Provide clear reasons ("Corrupted video") and a "Retry Job" button. + +### 6. Browser-Level Caching & Offline Patterns +* **Job List:** Cached for 1 minute via React Query. +* **Job Detail:** Cached in memory, updated via SSE. +* **Results:** `Stale-Time: Infinity`. Backend sends `Cache-Control: public, max-age=31536000, immutable` for generated clips. +* **Offline Pattern:** If internet drops, cached `Summary.md` remains accessible. Show "Offline - Reconnecting..." toast. + +### 7. Security Basics on the Client +* **XSS Considerations:** Use `DOMPurify.sanitize()` on the generated markdown before rendering to prevent script injection. +* **Token Handling:** Auth JWTs stored in HttpOnly, Secure Cookies, not localStorage. +* **Safe Downloads:** Assets served via short-lived Pre-Signed URLs (valid for 1 hour). +* **CSP:** Strict Content Security Policy headers blocking inline scripts. + +### 8. Debugging & Observability +* **Correlation IDs:** API requests include an `x-correlation-id` header. Failed jobs display: `Error: Processing failed. Ref ID: [abc-123]`. +* **Frontend Telemetry:** Datadog RUM for tracing clicks, Sentry for Error Boundaries. +* **Developer Diagnostics Panel:** Hidden shortcut (`Ctrl+Shift+D`) opening an overlay showing SSE Connection Status and raw JSON state. -You need to put your solution here. - +--- +> **🌟 Bonus: Interactive UI Prototype** +> While the prompt specified "no code," I took the initiative to build a React prototype to demonstrate how the SSE logging, resumable uploads, and complex UI states would function in reality. +> **[View the Video-to-Notes Platform.jsx prototype code here in my repo] -> (https://gist.github.com/DakshK-io/02eb6c5e5a087c7f9a7be0a942b896e3)** --- ## **Problem 2: LinkedIn Automation Platform (Frontend System Design)** @@ -43,10 +96,35 @@ You need to put your solution here. * **Debugging:** how you surface posting failures to user and capture details for support **Your Solution for problem 2:** - -You need to put your solution here. - +### 1. Screens & UX Flow +* **Connect:** OAuth landing page showing LinkedIn connection status and permissions requested. +* **Persona Editor:** Multi-step wizard collecting background, tone sliders (Formal <-> Casual), and "Do's/Don'ts" lists. +* **Drafts View:** A side-by-side or carousel view showing 3 generated post variants. +* **Approval & Scheduler:** A modal/drawer attached to a selected draft. Includes a timezone-aware calendar picker. +* **Post History:** A data grid filtering by Status (Draft, Scheduled, Published, Failed) with quick-edit actions. + +### 2. Form UX & Guardrails +* **Validation:** Persona inputs use strict character limits. "Do's/Don'ts" use a dynamic tag-input component to force concise rules. +* **Topic Input:** Real-time character counters and a "Generate" button that disables and shows a skeleton loader to prevent double-submissions. +* **Scheduling Guardrails:** The date-picker disables dates in the past and automatically converts the user's local browser timezone to UTC for the backend. + +### 3. API Calling Strategy (Lifecycle) +* **Draft Generation:** Uses a standard async `fetch`. Because generation takes 5-10 seconds, the UI shows a "Writing your posts..." skeleton state. +* **Optimistic UI vs Strict:** * *Approvals/Schedules:* Use **Strict Confirmation**. We wait for the 200 OK from the server before moving the post to the "Scheduled" tab to ensure we don't lie to the user about a post going live. + * *Deleting Drafts:* Use **Optimistic UI**. Hide the draft instantly for a snappy feel, rolling back only if the DELETE request fails. + +### 4. Browser Caching +* **Drafts & Schedules:** Cached using React Query. +* **Refetch Triggers:** Approving a draft triggers an invalidation of the `['schedules']` cache key, forcing a background refetch so the History screen is instantly up-to-date. +* **Persona:** Cached in `localStorage` as a fallback so the user doesn't lose their settings on a hard refresh. + +### 5. Debugging & Failure Surfacing +* **User-Facing:** If a post fails (e.g., LinkedIn Rate Limit), the History list shows a red "Failed" badge. Clicking it opens a user-friendly error toast (e.g., "LinkedIn rejected this post. Try again in 1 hour."). +* **Support Capture:** The error payload includes a `request_id`. A "Report Issue" button bundles this ID, the local browser timezone, and the Draft ID into an automated support ticket payload. --- +> **🌟 Bonus: Interactive UI Prototype** +> While the prompt specified "no code," I took the initiative to build a React prototype to demonstrate how the SSE logging, resumable uploads, and complex UI states would function in reality. +> **[View the LinkedInAuto.jxs prototype code here in my repo] -> (https://gist.github.com/DakshK-io/bfef0d80fbfee29dba726ead4e03a01d)** ## **Problem 3: DOCX Template → Bulk Generator (Frontend System Design)** @@ -61,11 +139,34 @@ You need to put your solution here. * **Downloads:** safe download UX (signed URL flow assumed), progress indicator **Your Solution for problem 3:** - -You need to put your solution here. - +### 1. Screens & UX Flow +* **Template Upload:** Drag-and-drop zone accepting only `.docx` MIME types. +* **Field Review/Editor:** A split-screen UI showing the parsed document on the left and a list of detected variables (e.g., `{{Name}}`) on the right for type-assignment (Text, Date, Currency). +* **Single Fill Form:** Auto-generated dynamic form based on the field schema. +* **Bulk Upload & Status:** CSV/XLSX uploader with a visual mapping step, followed by a live progress bar for the batch job. +* **Report Table:** A paginated grid showing row-by-row success/failure. +* **Downloads:** An artifact center to grab the final ZIPs or individual PDFs. + +### 2. Field UI & Validation +* **Dynamic Inputs:** The UI reads the schema and renders appropriate HTML inputs (e.g., `type="date"`, `type="number"`). +* **Inline Validation:** OnBlur validation checks for required fields or regex matches (e.g., valid emails) before allowing submission. + +### 3. Bulk UX (CSV Upload) +* **Constraints:** Client-side parsing (using `PapaParse`) to immediately validate column headers against the template schema *before* uploading. +* **Progress & Partial Success:** The bulk job view uses a WebSocket/SSE connection to show real-time progress (e.g., "Generated 450 / 1000"). If Row 42 fails, the job continues, and the UI marks Row 42 in red on the Report Table. + +### 4. Browser Caching +* **Metadata & Schema:** Template metadata and field schemas change rarely. They are cached heavily in memory via React Query (`staleTime: 24 hours`). +* **Bulk Reports:** Due to large data sizes (10k rows), the report table uses server-side pagination. Only the current page is cached in memory to prevent browser tab crashes. + +### 5. Downloads UX +* **Safe Downloads:** Clicking "Download ZIP" triggers a request for an S3 Pre-Signed URL. +* **UX:** The UI shows a "Preparing Download..." spinner. Once the URL is returned, the frontend creates a temporary `` tag to trigger the browser's native secure download prompt. --- - +> **🌟 Bonus: Interactive UI Prototype** +> While the prompt specified "no code," I took the initiative to build a React prototype to demonstrate how the SSE logging, resumable uploads, and complex UI states would function in reality. +> **[View the DOCX Bulk Generator Prototype.jsx prototype code here in my repo] -> (https://gist.github.com/DakshK-io/02eb6c5e5a087c7f9a7be0a942b896e3)** +> ## **Problem 4: Character-Based Video Series Generator (Frontend System Design)** **Goal:** Define characters once → create episode from story → view episode package (script/scenes/assets/render plan). [READ MORE ABOUT THE PROJECT](./char-based-video-generation.md) @@ -78,41 +179,88 @@ You need to put your solution here. * **Caching:** character library caching, episode package caching, asset thumbnails caching **Your Solution for problem 4:** - -You need to put your solution here. - +### 1. Screens & UX Flow +* **Character Library:** Grid view of saved characters. Clicking one opens a "Bible" modal (traits, voice, image). +* **Relationship Editor:** A visual node-graph or simple table mapping how Character A feels about Character B. +* **Episode Creator:** A multi-step form: Prompt Input -> Select Cast -> Choose Tone. +* **Episode Detail:** The core workspace. Displays generated Script, Shot List, and Voiceover lines in an accordion/list format. +* **Asset Gallery:** Displays generated scenes/images prior to video rendering. + +### 2. Consistency UX +* **Locked Profiles:** When viewing an Episode Detail, the character profiles used are shown with a "Locked / V1" badge. This clarifies to the user that editing the global character now won't retroactively break this specific episode. +* **Read-Only Context:** Hovering over a character in the script shows a tooltip of their relationships to ensure the user understands *why* the AI wrote a specific dialogue line. + +### 3. API Calling & Long-Running Jobs +* **Generation Job UI:** Generating video takes minutes. The UI uses Server-Sent Events (SSE) to display a multi-step progress bar (Writing Script -> Generating Audio -> Rendering Video). +* **Resume:** The job ID is stored in the URL (`/episodes/run/:jobId`). If the user closes the tab and returns, the `useEffect` hooks read the ID, re-establish the SSE connection, and pick up exactly where the progress bar left off. + +### 4. Browser Caching +* **Character Library:** Cached globally using React Query since characters are reused across all episodes. +* **Thumbnails:** Generated scene images rely heavily on the browser's native disk cache (`Cache-Control: max-age=31536000`). +* **Episode Package:** The script and text assets are cached in memory. If a user clicks "Regenerate Scene 3", only the specific scene object is invalidated and refetched, updating the UI optimistically. --- +> **🌟 Bonus: Interactive UI Prototype** +> While the prompt specified "no code," I took the initiative to build a React prototype to demonstrate how the SSE logging, resumable uploads, and complex UI states would function in reality. +> **[View the Character Video Prototype.jsx prototype code here in my repo] ->(https://gist.github.com/DakshK-io/fa1f5e7ab808f5a03eb1b50d58c56c68)** ## **Cross-Cutting** Answer these in **bullet points** (max 1 page total): -1. **Frontend stack choice** +1. Frontend stack choice + +Framework: React (via Vite). I prefer React for its massive ecosystem and component reusability. Vite provides near-instant Hot Module Replacement (HMR), making local UI iteration extremely fast. + +State Management: TanStack Query (React Query) for server state (handles caching, loading states, and retries automatically) paired with Zustand for lightweight global UI state (like active theme or upload queues), avoiding React Context re-render hell. + +Router: React Router for declarative, nested routing and route-based code splitting to keep bundle sizes small. + +UI Kit: Tailwind CSS combined with Radix UI (or shadcn/ui). Tailwind allows for rapid styling, while Radix provides unstyled, fully accessible UI primitives (modals, dropdowns) ensuring the app is screen-reader friendly without writing complex ARIA logic from scratch. + +2. API layer design + +Client & Typing: A custom wrapper around the native Fetch API. I would ideally use an OpenAPI generator to automatically create TypeScript interfaces from the backend schema, ensuring frontend and backend data contracts always match. + +Error Normalization & Interceptors: All API errors are intercepted and normalized into a standard format: { message, code, correlationId } so the UI can safely render fallback states. + +Retries & Dedupe: Handled natively by React Query, using exponential backoff for failed GET requests and automatically deduping identical requests made at the same time. + +Abort Controllers: Every API call and long-running stream (SSE) is tied to an AbortController. If a user navigates away from a page, the useEffect cleanup fires abort(), preventing memory leaks and saving bandwidth. + +3. Browser caching plan + +What & Where: * GET Responses (Job lists, characters) are cached in Memory via React Query. + +User Preferences (Persona configs, theme) are stored in localStorage. + +Generated Artifacts (Video clips, PDFs) rely on the HTTP Browser Cache via immutable headers. + +TTL/Invalidation rules: Job lists get a short TTL (e.g., 1 minute). When a user mutates data (e.g., approves a LinkedIn post), I explicitly call queryClient.invalidateQueries(['schedules']) to instantly background-refetch the fresh data. + +Job Status Updates: To avoid stale UI without aggressively polling the server, I would use Server-Sent Events (SSE). The server pushes real-time progress updates (e.g., 45% -> 50%) directly to the browser via a single, persistent connection. + +4. Debugging & observability + +Error Boundaries: Top-level React Error Boundaries prevent the whole app from crashing to a white screen, instead showing a friendly "Report a Problem" fallback UI. + +Correlation IDs: Every API request includes a generated x-correlation-id header. If an error occurs, the UI displays this ID to the user. + +Report Payload: Clicking "Report" bundles the Correlation ID, the user's browser Timezone, the exact URL route, and the error string into a JSON payload for support. -* EDIT YOUR ANSWER HERE: Framework (Next.js/Vue/etc), state management, router, UI kit, why. - `` +Specific Debugging Scenarios: -2. **API layer design** +Slow uploads: Open the Chrome Network tab to verify if the TUS protocol chunking is working correctly or if the network is throttling. -* Fetch/Axios choice, typed client generation (OpenAPI), error normalization, retries, request dedupe, abort controllers. - ` - ` +Failed downloads: Inspect the console for CORS errors or check if the Pre-Signed URL has expired. -3. **Browser caching plan** +Intermittent 500s: Look up the frontend-generated Correlation ID in backend logs (e.g., Datadog/Sentry) to trace exactly where the server-side crash happened. -* 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 -4. **Debugging & observability** +Token Storage: JWT Auth tokens are stored in HttpOnly, Secure Cookies. They are never stored in localStorage or sessionStorage to prevent malicious scripts from stealing them via XSS. -* Error boundaries, client-side logging approach, correlation id propagation, “report a problem” payload. -* How you would debug: slow uploads, failed downloads, intermittent 500s. - ` - ` +CSRF: I would ensure the backend sets SameSite=Strict on cookies and utilize anti-CSRF headers for all mutation requests. -5. **Security basics** +XSS Avoidance: Since the Video-to-Notes app renders generated Markdown, I will run all parsed HTML through DOMPurify before injecting it via dangerouslySetInnerHTML to strip out any potentially malicious