Expand Frontend.md with system design details

Frontend.md

@@ -28,8 +28,69 @@
 
 You need to put your solution here.
 
+1. Screens
+
+- Upload Screen – User uploads video and sees upload progress.
+- Jobs List Screen – Shows all jobs with status (Queued, Processing, Success, Failed).
+- Job Detail Screen – Shows job status, logs, progress, and retry option.
+- Results Screen – Displays Summary.md (rendered markdown), highlights with timestamps, and downloadable assets.
+
+2. UI States
+
+Each job can have the following states:
+
+- Loading
+- Queued
+- Processing (show spinner or progress bar)
+- Partial Output
+- Success
+- Failed (show error message and retry button)
+
+The UI should clearly display status badges and progress indicators.
+
+ 3. API Calling Plan
+
+After upload:
+POST /jobs → returns jobId.
+
+To check progress:
+GET /jobs/{jobId} every 5 seconds (polling).
+
+Stop polling when:
+- Status becomes Success
+- Status becomes Failed
+- User navigates away (using AbortController)
+
+Polling is simple and reliable for async long running jobs.
+
+4. Caching Strategy
+
+Cache the following in browser:
+
+- Job list (TTL: 30 seconds)
+- Job details (until status changes)
+- Final results (TTL: 5 minutes)
+
+Invalidate cache when:
+- New job is created
+- Retry is triggered
+- Job status changes
+
+5. Debugging Plan (Stuck Processing)
+
+If job remains in “Processing”:
+
+- Check Network tab for polling API responses
+- Verify status field in API response
+- Log jobId for tracing
+- Display correlation ID (if provided)
+- Show “Last updated” timestamp in UI
+
+If status never changes, likely backend-side issue.
+
 ---
 
+
 ## **Problem 2: LinkedIn Automation Platform (Frontend System Design)**
 
 **Goal:** Connect LinkedIn → persona setup → draft preview → approve → schedule → posting history. [READ MORE ABOUT THE PROJECT](./linkedin-automation.md)
@@ -46,8 +107,60 @@ You need to put your solution here.
 
 You need to put your solution here.
 
+1. Screens
+
+- Connect Screen – Connect LinkedIn account with OAuth.
+- Persona Editor Screen – Create and edit persona (tone, industry, target audience).
+- Drafts Screen – Show 3 generated draft variants with preview.
+- Approval Screen – Approve or regenerate draft.
+- Scheduler Screen – Select date and time for posting.
+- Post History Screen – View scheduled, posted, and failed posts.
+
+2. Form UX
+
+- Persona fields must be validated (required fields, max length limits).
+- Show inline validation errors.
+- Topic input should prevent empty submissions.
+- Scheduling must prevent past dates.
+- Show confirmation before final scheduling.
+- Disable submit button while generating drafts.
+
+  3. API Calling Plan
+
+- After persona setup → POST /generate-drafts.
+- Show loading state until drafts are returned.
+- Do not use optimistic UI for posting; wait for backend confirmation.
+- On approval → POST /schedule.
+- Refetch post history after scheduling.
+Handle API errors gracefully and show retry option.
+
+4. Caching Strategy
+
+Cache in browser:
+
+- Persona configuration
+- Drafts (short TTL: 5 minutes)
+- Post history (TTL: 1 minute)
+
+Invalidate cache when:
+- Draft is regenerated
+- Post is approved or scheduled
+- Posting status changes
+
+  5. Debugging Plan
+
+  If posting fails:
+
+- Display clear error message in Post History.
+- Show failure reason from API response.
+- Log requestId or correlationId for tracing.
+- Allow user to retry scheduling.
+- Capture request payload details for support debugging.
+
 ---
 
+
+
 ## **Problem 3: DOCX Template → Bulk Generator (Frontend System Design)**
 
 **Goal:** Upload template → review fields → single generate → bulk via CSV → ZIP download + per-row report. [READ MORE ABOUT THE PROJECT](./docs-template-output-generation.md)
@@ -64,8 +177,58 @@ You need to put your solution here.
 
 You need to put your solution here.
 
+1. Screens
+
+- Template Upload Screen – Upload DOCX template and validate file type.
+- Field Review Screen – Display detected fields and allow editing (required/default values).
+- Single Fill Form Screen – Fill template with single data input.
+- Bulk Upload Screen – Upload CSV file for bulk generation.
+- Bulk Run Status Screen – Show progress of bulk generation.
+- Report Table Screen – Display per-row success/failure report.
+- Downloads Screen – Download generated document or ZIP file.
+
+2. Field UI
+
+- Support field types: text, number, date.
+- Allow marking fields as required.
+- Support default values.
+- Inline validation for incorrect inputs.
+- Highlight missing required fields before submission.
+
+  3. Bulk UX
+
+- Accept only valid CSV format.
+- Validate headers before processing.
+- Optional mapping UI to match CSV columns with template fields.
+- Show progress bar for bulk processing.
+- Display partial success if some rows fail.
+- Show row-level error messages in report table.
+
+  4. Browser Caching
+
+ Cache in browser:
+
+- Template metadata
+- Field schema
+- Bulk report pagination data
+
+ Use short TTL (2–5 minutes).
+
+Invalidate cache when:
+- New template is uploaded
+- Bulk run is triggered
+- Report status changes
+
+5. Downloads
+
+- Use signed URLs for secure downloads.
+- Show download progress indicator.
+- Handle failed downloads with retry option.
+- Disable download button until generation completes.
+
 ---
 
+
 ## **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)
@@ -81,38 +244,101 @@ You need to put your solution here.
 
 You need to put your solution here.
 
+1. Screens
+
+- Character Library Screen – Create, edit, and view all characters.
+- Relationship Editor Screen – Define relationships between characters.
+- Episode Creator Screen – Create episode from story prompt and select characters.
+- Episode Detail Screen – View generated episode (script, scenes, render plan).
+- Asset Gallery Screen – View and preview generated assets (images, videos, thumbnails).
+
+2. Consistency UX
+
+- When episode is created, lock selected character profile version.
+- Display version badge for characters used in episode.
+- Prevent automatic updates if character is edited later.
+- Show clear indication if character has a newer version available.
+
+3. API Calling Plan
+
+- After episode creation → POST /episodes → returns episodeId.
+- Poll episode status every 5 seconds using GET /episodes/{episodeId}.
+- Show progress indicator during generation.
+- Allow user to leave page and resume viewing later.
+- Stop polling when status becomes Success or Failed.
+
+4. Caching Strategy
+
+Cache in browser:
+
+- Character library (TTL: 5 minutes)
+- Episode details (until status changes)
+- Asset thumbnails for faster loading
+
+Invalidate cache when:
+- Character is edited
+- New episode is created
+- Episode status updates
+
 ---
 
+
 ## **Cross-Cutting** 
 
 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.
-  `<EDIT YOUR ANSWER HERE>`
+  `
+ Frontend Stack Choice
+   Framework: React (SPA) for building interactive dashboard-style applications.
+   Routing: React Router for structured client-side navigation.
+   Server State: React Query for API caching, polling, retries, and background refetching.
+   Local State: useState / useReducer for component-level UI state.
+   Styling: Tailwind CSS for consistent and scalable UI.
+   Architecture: Modular, reusable component-based design.`
 
 2. **API layer design**
 
 * Fetch/Axios choice, typed client generation (OpenAPI), error normalization, retries, request dedupe, abort controllers.
-  `
-  <EDIT YOUR ANSWER HERE>`
+
+  API Layer Design
+   Create a dedicated api/ folder to centralize all API calls.
+   Use Axios for HTTP requests with a configured base URL and interceptors.
+   Integrate React Query for caching, background refetching, retries, and polling.
+   Implement global error handling and loading states.
+   Keep API logic separate from UI components for better scalability and maintainability.`
 
 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.
-  `
-  <EDIT YOUR ANSWER HERE>`
+
+  Browser Caching Plan
+   Use React Query for caching GET API responses (in-memory).
+   Apply short TTL (30s–5 min) based on data type.
+   Invalidate cache on create/update/retry actions.
+   Use polling or background refetch to prevent stale job status.
 
 4. **Debugging & observability**
 
 * Error boundaries, client-side logging approach, correlation id propagation, “report a problem” payload.
 * How you would debug: slow uploads, failed downloads, intermittent 500s.
-  `
-  <EDIT YOUR ANSWER HERE>`
+
+  Debugging & Observability
+   Use Error Boundaries to prevent full app crashes.
+   Log API errors via Axios interceptors.
+   Display correlationId/requestId for tracing.
+   Use Network tab and request logs to debug slow or failed operations.
 
 5. **Security basics**
 
 * Token storage approach, CSRF considerations (if cookies), XSS avoidance for markdown rendering, safe file download patterns.
-  ` A<EDIT YOUR ANSWER HERE>`
+
+  Performance & Optimization
+   Store tokens in secure HttpOnly cookies (preferred).
+   Sanitize markdown to prevent XSS.
+   Validate file uploads (type and size).
+   Use signed URLs for secure downloads.
+   Implement CSRF protection if using cookies.