docs/implementation_plan.md

Implementation Plan

Trang Thai Hien Tai

Du an da chuyen tu prototype Taekwondo/Streamlit sang ung dung Reflex phan tich bai tap hit dat. Luong xu ly production hien tai nam trong cac module push_up/* va reflex_frontend/*.

Kien Truc Chinh

Reflex UI
  -> upload video hoc vien
  -> push_up.analysis_service.analyze_pushup()
  -> VideoProcessor + MediaPipe Pose
  -> PushUpEvaluator
  -> PushUpRuleEngine
  -> frame artifacts + rule-based arrows
  -> optional NVIDIA VLM feedback
  -> Reflex result cards

Module Chinh

• reflex_frontend/state.py: quan ly upload, tien trinh xu ly, state ket qua.
• reflex_frontend/ui.py: giao dien trang chu, danh sach bai tap, trang phan tich hit dat, card ket qua tung rep.
• push_up/processor.py: doc video, phat hien huong nguoi tap, flip neu can, trich xuat landmark theo frame.
• push_up/engine.py: boc MediaPipe Pose, tinh cac chi so kinematics nhu elbow angle, hip angle, body line angle, depth signal.
• push_up/evaluator.py: segment rep, can chinh voi template bang DTW, ket hop diem rule score va DTW score.
• push_up/rules.py: phat hien loi ky thuat bang nguong deterministic.
• push_up/analysis_service.py: orchestration cua toan bo flow, tao payload cho UI, luu artifact, ve arrow.
• push_up/feedback_graph.py: goi text LLM/VLM qua NVIDIA OpenAI-compatible API va validate JSON feedback.
• scripts/run_pushup_eval_tests.py: batch test tat ca video trong data/tests va xuat file JSON tong hop.

Luong Phan Tich Video

1. UI luu video upload vao thu muc tam cua Reflex.
2. prepare_template_cache() dam bao video mau da duoc xu ly va cache landmark tai data/processed/pushup_template.pkl.
3. VideoProcessor doc video hoc vien, lay mau frame, auto flip neu nguoi tap nam nguoc huong template.
4. PoseEngine trich xuat 33 landmark pose va tinh kinematics.
5. PushUpEvaluator segment rep dua tren depth signal va elbow angle.
6. Moi rep duoc so sanh voi golden template bang DTW va pose similarity.
7. PushUpRuleEngine chay rule-based checks:
   • not_deep_enough
   • hip_sag
   • body_not_straight
   • head_misaligned
   • hip_pike
8. analysis_service tao card ket qua tung rep, main error, feedback rule-based, va summary.
9. Khi save_artifacts=True, app luu frame hoc vien/mau va ve arrow vao frame hoc vien.
10. Neu rep co rule-based error va co NVIDIA_API_KEY, VLM duoc goi de sinh feedback chu cho rep loi.

Quyet Dinh Thiet Ke

• Rule engine la nguon quyet dinh loi chinh, diem rule, feedback rule-based va arrow target.
• VLM khong duoc dung de quyet dinh toa do arrow vi de tra sai vi tri tren nen anh.
• VLM chi sinh feedback ngan bang tieng Viet dua tren anh hoc vien, anh mau va rule context.
• Arrow label dung tieng Viet co dau va duoc render bang Pillow de tranh loi Unicode cua OpenCV.
• Ket qua test batch mac dinh tat VLM de lap lai, nhanh hon va khong ton API.

Viec Can Lam Tiep

• Them expected assertions vao batch test, vi du hv01_mong_cao phai co hip_pike.
• Luu anh artifact cho test run co chon loc thay vi tat ca rep neu can giam dung luong.
• Tach llm_* field thanh vlm_* trong payload/UI de ten bien khop voi y nghia hien tai.
• Them exercise registry neu mo rong sang bai tap khac.