Alice App – Technical Journal Series

Journal 01 – System Overview & Philosophy

Alice is a school management system built with Laravel + Inertia + React, designed with three primary roles:

Admin – manages academics, finance, teachers, students
Teacher – mobile-first daily usage
Customer (Parent) – non-tech-savvy, mobile-only usage

Core principles

Mobile-first for teachers & parents
Admin UI is compact, dense, efficient
Backend is the source of truth
Avoid frontend hacks when backend clarity is possible
Prefer explicit data models over “magic” behavior
Real-world workflows > abstract software purity

Journal 02 – Authentication & Roles

Roles

admin
teacher
parent (customer)

Customer (Parent) auth

Login/register via phone number + password
Role assigned as parent
Session is remembered by default
On logout, phone number is pre-filled next time

Reasoning:

Parents are lazy, non-technical, and mobile-first.
Reduce friction to the absolute minimum.

Journal 03 – Customer Layout & UX

Customer layout

No admin menu
Respects:
- iPhone top notch
- safe-area bottom
Uses Alice theme where possible, otherwise high-readability colors

Naming

Dashboard is called “Góc phụ huynh”
- Familiar
- Non-technical
- Emotionally aligned with parents

Journal 04 – Student Resolution Model (Critical)

Customers do not directly own students.

Resolution flow:

Customer (user: parent)
  → linked Finance Contact
    → associated Student(s)

This model is reused everywhere:

Schedule
Homework
Invoicing
Progress tracking

Finance Contact is the “real identity” of a parent in the system.

Journal 05 – Customer Dashboard Features

Dashboard acts as a hub, not a data dump.

Features:

Weekly schedule link
Homework link
Each student shown separately
If multiple students → choose student
If one student → auto-select

Journal 06 – Weekly Schedule (Customer)

Page

/customers/schedule

Behavior

One week view
Shows:
- Class time
- Class name
Uses same source-of-truth as Admin student calendar
Mobile-friendly stacked days (no wide grids)

Visit tracking

Every visit logs:

user_id
visited_at

Stored in:
customer_schedule_visits

Used later in:

Insights > Customers (visit count + last visit)

Journal 07 – Homework System (Admin)

Homework concept

Homework is skill-based, not file-based.

4 skills:

Listen
Speaking
Reading
Writing

Each skill supports:

Multiple links
Optional labels
Ordered lists

Homework also supports:

Multiple attachments (photos/files)

Reason:

Real homework is messy, contextual, and link-heavy.

Journal 08 – Homework Data Model

Core tables

homework
homework_links
homework_attachments
homework_students
homework_skill_progress

Progress tracking

Per:

homework
student
skill

Status:

pending
done

Parents update progress, admins observe.

Journal 09 – Customer Homework UX

Entry flow

Dashboard → Homework
One student per page (non-negotiable)

Routes:

/customers/homework (entry / chooser)
/customers/students/{id}/homework

UX rules

One child at a time
Large tap targets
Expand/collapse homework items
Vietnamese, parent-friendly copy

Journal 10 – In-App Video Playback (Listening)

Listening skill YouTube links:

Open inside the app
Modal popup
Embedded player
No redirect to YouTube

Constraints:

Only Listening
Only YouTube
Graceful fallback if parsing fails

Reason:

Parents should not “leave the app” mentally or technically.

Journal 11 – Homework Progress (Admin)

Admins need visibility, not control.

Admin views:

Homework list:
- Progress summary per homework
Homework detail:
- Per student
- Per skill
- Last updated

Completion rule:

Homework is complete for a student only when all required skills are done.

Journal 12 – Tasks System (Admin)

Tasks are daily operational work, not academic content.

Used for:

Teacher duties
Follow-ups
Classroom operations

Tasks have:

Title (auto-generated)
Description
Due date/time
Status
Teachers
Students

Journal 13 – Task Title Strategy

Title is generated, not manual.

Rule:

Combine teacher name + student name(s)
Keep short, mobile-readable

Example:

Cô Lan – Minh

Reason:

Teachers scan tasks on mobile.
Titles must be human-readable at a glance.

Journal 14 – Weekly Recurring Tasks

Tasks can be:

One-off
Weekly recurring

Implementation:

Template task
Generated child tasks
Same teachers/students
Same weekday + time

Edits:

Template edits affect future tasks only
Past tasks remain unchanged

Journal 15 – Teacher “My Tasks” (Mobile-first)

Route

/teacher/tasks

UX

Cards, not tables
One-tap status update
Filter chips on one horizontal line
Lightweight, not button-heavy

Statuses:

pending
in_progress
done

Journal 16 – Teacher Notification Badge

Teacher layout shows badge when:

pending or in_progress tasks exist

Badge:

Numeric
Appears globally
Disappears when all tasks are done

Purpose:

Passive reminder, not interruption.

Journal 17 – Finance: Salary & Overtime

Teacher

Can submit overtime
Mobile-first form
Status = pending

Admin

Approves / rejects overtime
Pending overtime is NOT counted in salary calculations

Principle

Money only counts when approved.

Journal 18 – Finance UI Consistency

Admin > Finance pages:

Compact tables
Unified spacing
Tabs behave like real tabs
No floating gaps

UI changes are visual only, never logic.

Journal 19 – Invoicing & Enrollment

Invoices generated with reference key
Reference used to match bank transactions
Invoice paid → enrollment renew appears
Backend handles matching & state transitions

Journal 20 – Insights System

Insights are observational, not transactional.

Insights > Customers

Visit count
Last visit time
Linked Finance Contact

Insights > Enrollments

Days attended
Payment state
Manual overrides allowed

Journal 21 – Timezone Handling (Lesson Learned)

Bug observed:

Due date shows -7 hours

Decision:

Fix on backend only
Explicit Asia/Ho_Chi_Minh handling
Frontend is passive renderer

Rule:

Timezones are a backend responsibility.

Final Note

This system was designed by:

observing real teachers
observing real parents
respecting human behavior over technical elegance