MyClass — Tutor Management App

MyClass is an open-source, self-hosted web app for private tutors. Manage students, weekly schedules, session billing, calendar views, and PWA push reminders — with Vietnam timezone (Asia/Ho_Chi_Minh) and VND money formatting built in.

Designed for a single tutor (one account owns their students). Not a multi-tenant marketplace.

Most scheduling/billing tools assume multi-teacher centers or SaaS subscriptions. MyClass is built for independent tutors who want to self-host student schedules and invoices, with correct Vietnam calendar semantics and soft-delete data safety. If you teach privately and already run Docker (or can), you can run the whole stack on one machine.

• Students — profiles, subjects, soft-delete safety
• Schedules — recurring weekly slots (dayOfWeek + HH:MM)
• Bills & sessions — generate sessions, mark paid/unpaid, edit session notes
• Calendar — session view + fixed weekly schedule view
• Report — monthly and all-time invoice totals, full bill list, TanStack Charts visualizations
• Settings — profile, notification preferences, web push
• PWA — installable; offline shell caching (API never cached)
• Docker — Postgres + app + nightly DB backups

• Next.js 15 (App Router) · TypeScript · TanStack Query · TanStack Charts
• PostgreSQL · Sequelize · umzug migrations
• NextAuth (email + password / credentials)
• Tailwind CSS · Radix UI · Vitest (pure logic)

• Docker & Docker Compose (recommended)
• Node.js 20+ and Yarn for local development

git clone https://github.com/t1112000/tutor-management-app.git
cd tutor-management-app
cp .env.example .env

Edit .env and set at least:

docker compose up --build

App: http://localhost:3000 (port may match your compose mapping).

Create the first user (from a machine with Node, against the same DB):

yarn install
yarn set-password <email> <password> [name]

Hướng dẫn tóm tắt bằng Tiếng Việt để chạy thử MyClass qua Docker. Xem phần Quick start (Docker) và Environment ở trên nếu cần chi tiết đầy đủ về biến môi trường.

1. Clone repo: git clone https://github.com/t1112000/tutor-management-app.git
2. Vào thư mục dự án: cd tutor-management-app
3. Tạo file cấu hình: cp .env.example .env
4. Mở .env và điền các biến bắt buộc (AUTH_SECRET, NEXT_PUBLIC_APP_URL, v.v. — xem bảng ở phần Quick start phía trên). Không commit file .env hay bất kỳ secret nào.
5. Khởi chạy toàn bộ stack: docker compose up --build
6. Mở ứng dụng tại http://localhost:3000
7. Tạo tài khoản đầu tiên: yarn install, sau đó yarn set-password <email> <mat-khau> [ten]
8. Đăng nhập lần đầu bằng email và mật khẩu vừa tạo ở bước 7

cp .env.example .env
# Point DATABASE_URL at a local Postgres instance
yarn install
yarn db:migrate
yarn set-password you@example.com 'your-password' 'Your Name'
yarn dev

CI runs typecheck → lint → test → build on every PR to main.

See .env.example. Required at runtime:

• DATABASE_URL
• AUTH_SECRET
• AUTH_TRUST_HOST (typically true behind a reverse proxy)

Web push (optional but needed for reminders on device):

• NEXT_PUBLIC_VAPID_PUBLIC_KEY (inlined at build time)
• VAPID_PRIVATE_KEY
• VAPID_EMAIL (e.g. mailto:you@example.com)

NEXT_PUBLIC_* values are baked into the client bundle at build time. With Docker, pass them as build args (already wired in docker-compose.yml).

• Ownership: every API route uses requireUser() and scopes data with findOwnedStudent / findOwnedBill (createdBy + deletedAt: null).
• Soft deletes: Student and Bill are soft-deleted; queries must filter deletedAt themselves (helpers do this).
• Time: all date logic uses helpers in src/lib/time.ts (Vietnam time). Prefer those over raw Date / UTC assumptions.
• Single replica: daily reminders (node-cron at 07:00 VN) and the in-process sign-in rate limiter assume one app instance. Multiple replicas will duplicate reminders.

Web push on iOS requires iOS 16.4+ and the app added to the Home Screen. Notifications are not delivered in Safari tabs — only standalone/PWA mode.

Product UI lives under the dashboard routes (/students, /bills, /calendar, /report).
Community-contributed screenshots (no real PII) can go in docs/screenshots/ — see open issues labeled good first issue.

Contributions are welcome — docs, bugfixes, accessibility, and carefully scoped features. See CONTRIBUTING.md.

Looking for a first task? Check good first issues or the templates in docs/good-first-issues.md.

Please read SECURITY.md for vulnerability reports and CODE_OF_CONDUCT.md.

Agent-oriented project notes: AGENTS.md, CLAUDE.md.
OSS readiness & Codex for Open Source checklist: docs/oss-scorecard.md.

MIT — free to use, modify, and self-host.