Chill Bits

Alice Technical Journal

—

Homework System: Upload Queue, Video Processing, Copy/Clone, and UX Simplification

Context

Alice is a Laravel + Inertia + React application for academic management.
This journal documents a sequence of production changes and bug fixes related to Homework, focusing on Customers, Teachers, and Admins.

The goal of these changes was:

  • Improve UX trust for parents
  • Reduce cognitive load
  • Keep backend precise while frontend remains calm
  • Preserve DB-driven state and queue-based processing

1. Customers > Homework: Progress & Proof Upload

1.1 Progress Tracking (Baseline)

  • Homework consists of 5 skills: Listening, Speaking, Reading, Writing, Grammars.
  • Each skill contains multiple links.
  • Progress is tracked at link level via checkboxes.
  • Skill completion is derived, not manual:
    • A skill is done only when all links are completed.
  • Manual “Mark as done” button was removed.
  • Backend recalculates skill status on every toggle.
  • UI relies strictly on persisted DB state.

Design principle:

Never let frontend guess progress state.

1.2 Multi-file Proof Upload (Images & Videos)

Implemented Behavior

  • Customers can upload multiple images/videos at once.
  • File input: accept="image/*,video/*" (Android-safe).
  • Files are uploaded sequentially, not in parallel.
  • Each file is treated independently:
    • One failure does not block others.

Frontend Queue (Google Drive–style)

  • Local upload queue per skill.
  • Each item shows:
    • filename
    • type (image/video)
    • status
  • Queue persists across page refresh via DB reload.
  • No frontend polling.

2. Video Processing Architecture

2.1 Video Lifecycle

Backend statuses:

  • uploaded
  • scheduled
  • processing
  • ready
  • failed

Rules:

  • Original video uploads directly to Cloudflare R2.
  • Metadata is saved immediately.
  • ffmpeg processing only runs inside queued jobs.
  • Controllers never execute media processing.

2.2 Failure Strategy (Final Decision)

  • If optimization fails:
    • Keep original video
    • Status = failed
    • No auto-retry
  • Playback logic:
    • Optimized exists → play optimized
    • Otherwise → fallback to original

Principle:

Optimization failure must never block usage.

3. UX Simplification for Customers (Important Decision)

Problem

Customers were exposed to internal queue concepts (scheduled, spinners).

This caused:

  • Confusion
  • False sense of waiting/blocking
  • Unnecessary cognitive load

Final Mapping (Customer UI Only)

Backend StatusCustomer UI
uploaded OR scheduledĐã tải lên (green, no spinner)
processingĐang xử lý (spinner allowed)
readyHoàn tất (green)
failedThất bại (red)
  • uploaded and scheduled are merged.
  • No spinner for queued/scheduled state.

Key insight:

Parents care that the file is accepted, not how the queue works.

Admin and Teacher UIs still see real backend states.

4. Debugging & Observability

Dedicated Log Channel

  • homework-proof

Used for:

  • Proof uploads (request → validation → R2 → DB → job → response)
  • Video job lifecycle
  • Link progress updates

Correlation Strategy

  • Each upload/file has a correlation_id.
  • Logs include:
    • homework_id
    • student_id
    • skill
    • media_id
    • status transitions

Outcome:
Silent UI failures became traceable timelines.

5. Critical Bug: Video Upload 500 Error

Symptom

  • Uploading multiple videos showed frontend error:
    • syntax error, unexpected token ";", expecting ")"

Root Cause

  • PHP ParseError in ProcessVideoProof.php.
  • Invalid syntax near ffmpeg command building.
  • Job class failed to autoload.
  • DB insert succeeded, but controller crashed before response.

Fix

  • Correct PHP syntax (lintable, parse-safe).
  • Ensure:
    • DB insert happens before job dispatch.
    • Dispatch failure does not roll back metadata.
  • Controller returns success if upload succeeded, even if job dispatch fails.

Lesson:

PHP syntax errors are fatal at load time — no try/catch can save you.

6. Teachers > Homework: Copy / Clone Feature

Initial State

  • Teacher could copy homework content:
    • Skills + links
  • Assignments (students list) were NOT copied.

Enhancement

  • Added optional checkbox:
    • “Sao chép danh sách học sinh”
  • Default: OFF (safe by default).
  • When enabled:
    • Copy homework–student assignments.
    • Skip unauthorized or soft-deleted students.
    • Transactional copy.

7. Admin > Academic > Homework: Copy / Clone Feature

Change

  • Implemented the same copy feature as Teacher:
    • Copy skills + links
    • Optional copy of student assignments
  • Admin UI mirrors Teacher UX.
  • Logic reused; no duplication.

Principle:

Same behavior, same mental model — role only affects authorization.

8. Teacher Homework Edit Bug (PUT vs POST)

Issue

  • Editing homework caused:
    • MethodNotAllowedHttpException
    • PUT not supported, only POST route existed.

Fix

  • Align frontend submission method with backend routes:
    • Either add PUT/PATCH route
    • Or update frontend to use POST update endpoint
  • Cleared route cache and verified route list.

9. Key Architectural Principles Reinforced

  1. DB-driven UI state
    • No optimistic guessing
    • No frontend polling
  2. Queue is backend truth
    • Frontend reflects persisted state only
  3. Customers see outcomes, not internals
    • Simplified status language
    • Calm, trustable UI
  4. One failure ≠ system failure
    • File-level isolation
    • No cascading crashes
  5. Observability before features
    • Logs made fixes obvious
    • Reduced “it works after refresh” mysteries

Final Note

At this stage, the Homework system is:

  • Predictable
  • Recoverable
  • Human-friendly on the surface
  • Technically strict underneath

This balance is intentional — and repeatable if the system ever needs to be rebuilt.