Alice – Technical Journal (Reconstruction Notes)

0. Core Philosophy & System Principles

Product mindset

Mobile-first for Teachers & Customers (parents)
Admin UI: compact, dense, operational
Avoid frontend hacks → backend rules first
Explicit data models > clever abstractions
Teachers & parents should never feel “lost” by redirects

Stack

Laravel (backend)
Inertia + React (frontend)
Tailwind-based design system
Cloudflare R2 for media storage

1. Roles & Layout Strategy

Roles

Admin: full control (academic, finance, insights)
Teacher: operational workflows (tasks, homework approval, homework management)
Customer (Parent): read + submit progress, minimal friction

Layouts

Teachers layout is the reference design:
- Heading bar
- Hamburger menu
- Logout inside menu
- Consistent typography & spacing
Customers layout
- Fully aligned with Teachers layout
- Hamburger menu
- Menu shows phone number only (no email)
- Logout inside menu
- All Customers pages share ONE layout

2. Academic > Homework (Core System)

Homework Structure

Homework has 5 skills:
1. Listening
2. Speaking
3. Reading
4. Writing
5. Grammars (same behavior as Listening)

Skill Rules

All skills support multiple links
Attachments
- ONLY allowed on Reading
- Grammars does NOT allow attachments
- Enforced backend-side

Progress Model

Progress is per:
- Homework
- Student
- Skill
Status:
- done / pending
Homework is “completed” only if all 5 skills are done

3. Homework Creation & Management

Admin > Academic > Homework

Create / Edit homework
Assign students by class
- Class selector first
- Students list filtered by class
- Select-all per class
- Switching classes does not lose selections
Homework table shows:
- Compact rows
- Approval state column:
  - No progress
  - Pending approval
  - Approved (all completed skills approved)
Admin can delete homework
- Confirmation modal
- Safe handling of:
  - Progress
  - Approval records
  - Completion proofs
  - Attachments

4. Teacher > Homework

Teacher > Homework = Hub

Two entry points:

Approve
Manage

(No teacher assignment logic – one teacher handles all homework)

Teacher > Homework > Approve

Purpose: review & approve parent-submitted progress

List homework items needing review
Detail view:
- All 5 skills
- Parent-marked progress
- Completion proofs (photos/videos)
Approval:
- Per skill
- Optional “Approve all”
Approval metadata:
- approved_by
- approved_at
If parent changes progress → approval resets

Teacher > Homework > Manage

Purpose: operational control

List all homework
Read-only review of content
Create new homework
- Same structure as Admin
- Same validation rules
- Appears everywhere immediately (Admin / Customers)

5. Customers > Homework

Flow

Homework List (per student)
Homework Detail

NO student selection screen

Homework List

Shows all homework for the student
Each item shows:
- Title
- Due date
- Progress summary (X/5)
Used for visit tracking

Homework Detail

5 skills displayed
In-place updates only (no redirects)
YouTube listening opens in-app modal

Completion Proof (Parent Upload)

Parents can upload photos/videos per skill
Stored in R2
Separate from homework attachments
Parent can delete their uploads
Teachers can view proofs during approval

Vietnamese UI label:

“Ảnh / video bài làm của bé”

6. Customers > Dashboard

Layout & Theme

Same as Teachers layout
Hamburger menu
Logout in menu
Menu shows phone number only

Student Cards

Redesigned to be:
- Soft colors
- Avatar initials
- Calm, premium, friendly
No logic changes

Action Tiles

Replaced big buttons with kid-friendly tiles:

“Xem lịch học” (calendar icon)
“Bài tập về nhà” (book icon)
Soft background colors
Minimal borders
Equal visual weight

Homework tile shows badge:

Count of homework NOT fully completed

7. Visit Tracking & Insights

Schedule Visits

Table: customer_schedule_visits
Deduplicated by:
- customer_id + student_id
On visit:
- Increment visit_count
- Update last_visited_at
Existing duplicates merged (sum count, latest timestamp)

Homework Visits

Only track Homework LIST page
Table: customer_homework_visits
Deduplicated by:
- customer_id + student_id

Insights > Customers

Replace wide visit columns with compact summary:
- 📚{homework} 📆{schedule}
Below Customer table:
- Section listing Finance Contacts
  - Linked to Students
  - NOT linked to Customer Accounts
  - Action to link or create customer

8. Authentication & Security

Reset Password (Admin)

Admin CANNOT set password directly
Admin action:
- Generate reset-password link
- Copy to clipboard
- Admin sends link manually
Token-based, time-limited

9. Make-up Classes (Buổi học bù)

Concept

Missed sessions become Make-up classes
Vietnamese term: “Buổi học bù”

Status wording (recommended)

Chưa sử dụng
Đã sử dụng

Data Model

Each make-up record:

student_id
original_missed_date
status (available / used / cancelled)
used_date (nullable)
reason / notes
created_by
timestamps

Admin > Academic > Make-up Classes

View / filter records
Create manually
Mark as used
Cancel if needed

Scan missed classes

Scan last 1 month
Based on attendance = absent
Exclude present / late
Deduplicate against existing make-up records
Bulk create after admin review

Customers > Buổi học bù

Vietnamese UI only

Features:

Show number of remaining make-up classes
- “Còn lại: X buổi”
List records as mobile cards
For “Chưa sử dụng”:
- Action: “Chọn ngày học bù”
Picker shows:
- Schedule sessions from current week only
- Prevent:
  - Past days
  - Double-using same session
Save in-place, no redirect

10. Media Storage (R2)

Cloudflare R2

Used for:
- Homework attachments
- Completion proofs
- Images / videos system-wide
Metadata stored in DB
Authorization-aware access
Migration path for legacy files

11. Design Constraints (Non-negotiable)

No redirect-based UX for progress updates
Backend validation always wins
No heavy tables for parents/teachers
Compact Admin tables
Vietnamese copy must be:
- Natural
- Parent-friendly
- Non-administrative tone