Ideogram Learning

Nền tảng học ngôn ngữ Vietnamese-first, ưu tiên tiếng Nhật khi ra mắt, với Next.js web, Expo mobile, Supabase/PostgreSQL, worker chấm placement, AI tutor có giới hạn và đồng bộ offline bền vững. Chinese và Korean đã có contract nhưng đang được khóa sau release gate riêng.

Trạng thái: source đủ cho repository preview và portfolio review; vẫn là pre-beta foundation, chưa phải production deployment. Repo không giả lập bài học đã phát hành, audio đã được cấp quyền, native background execution hay hosted runtime khi chưa có bằng chứng thật.

Xem project tour · Docs index · Đọc kiến trúc · Chạy local · Release docs · Xem release checklist · Known limitations

Visual tour

Project tour dưới đây được chụp từ route /showcase chạy thật và không cần tài khoản. Bốn ảnh tĩnh là tour chính; project-tour.gif chỉ là bản động tùy chọn.

Hero Public preview entry point and visual identity.	Foundation Implemented slices and pre-beta foundation scope.
Evidence Architecture proof and the boundary between implemented and target state.	Roadmap Still-open browser, device, hosted, and media gates.

Mở project tour dạng GIF (4 frame)

Bằng chứng web runtime

Ảnh dưới được chụp từ Chromium local sau khi đăng nhập để kiểm chứng IndexedDB, offline queue và trạng thái Background Sync. Đây không phải bằng chứng hosted production hay cross-browser certification.

Mobile design handoff

Năm màn hình Today, Review, AI tutor, Progress và Profile được chuẩn hóa vào cùng một khung điện thoại. Đây là Stitch design handoff, không phải native-device runtime proof.

Kiến trúc hệ thống

Mở sơ đồ SVG đầy đủ · Đọc giải thích kiến trúc

Luồng học và đồng bộ offline

Các hình trên là bằng chứng ở phạm vi khác nhau. Xem docs/media/README.md để biết nguồn, cách tái tạo và giới hạn của từng asset.

Sản phẩm hiện có

Surface	Đã triển khai	Giới hạn trung thực
Web	Protected learner shell, catalog, review, placement, offline media status, IndexedDB queue, project showcase	Chưa có hosted production/cross-browser certification
Expo mobile	Session hydration, onboarding/placement, catalog, review, SecureStore queue, optional BackgroundTask	Cần proof trên thiết bị thật và native release pipeline
Learning engine	Japanese-first contracts, activity submission, SRS/review receipts, placement scoring jobs	Nội dung authored vẫn review-only; speaking/writing evaluator chưa có
AI tutor	Authenticated server-only bounded turn, consent/quota ledger, disabled by default	Chưa có grounded retrieval, SSE, durable history hay offline tutor queue
Worker	Enabled-startup logging, optional placement-scoring drain và non-root worker image	Container health is process liveness, not database readiness; chưa deploy
Offline media	Manifest/checksum/cache contract và trạng thái unavailable đúng sự thật	Chưa có audio được duyệt quyền hoặc playback proof

Luồng kiến trúc

Next.js web ─┐
             ├─ canonical API/contracts ─ learning engine ─ Supabase/PostgreSQL
Expo mobile ─┘              │                    │
                            ├─ offline queues    ├─ placement jobs → worker
                            └─ bounded AI route  └─ governed content/media

Workspace chính:

apps/web/           Next.js App Router, API handlers, learner UI
apps/mobile/        Expo/React Native learner application
apps/worker/        Node placement-scoring worker
packages/           Contracts, auth, API client, learning engine, sync, UI config
supabase/           Migrations, RLS policies, pgTAP tests
content/            Governed source, manifests, rights ledger, media registry
docs/               Architecture, contracts, runbooks, release evidence
plans/              CK implementation plans and phase reports

Chạy local

Yêu cầu Node >=24.12.0 <25, pnpm >=11.0.9 <12 và Docker khi chạy Supabase.

corepack enable
corepack pnpm install --frozen-lockfile
pnpm check:env
pnpm dev

Trước khi chạy tính năng cần secret, tạo file local bị ignore:

Copy-Item .env.example .env.local

Trên macOS/Linux dùng cp .env.example .env.local. Không đưa output pnpm supabase:status vào log chia sẻ vì có thể chứa credential local.

Supabase local

pnpm supabase:start
pnpm supabase:stop

Kiểm tra chất lượng

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm content:lint

CI kiểm tra workspace contracts, docs package, governed content, peer/Expo compatibility, lint, type safety, tests, production build và database regressions. Sau các gate đó, web/worker images mới được build, smoke-test, Trivy scan và publish kèm SBOM/provenance. Browser/device E2E, accessibility, load và coverage threshold vẫn là release gate chưa hoàn tất — xem release-checklist.md.

API surface đã triển khai

• Health và auth session/email OTP/callback/sign-out.
• Learning catalog, offline-media manifest và review queue.
• Placement session create/read/answer/submit.
• Activity và review submission.
• Bounded AI tutor turn.

Chi tiết method, validation và response contract nằm trong docs/api-contract.md. Không có API nào ngoài tài liệu đó được tuyên bố là public contract.

Content và quyền sử dụng

Japanese N5 pilot hiện có 2 units, 12 lessons, 156 vocabulary/review entries, 40 listening scripts và 25 placement prompts. Nội dung vẫn ở trạng thái review; audio registry rỗng và quyền redistribution chưa được duyệt.

pnpm generate:ja-n5-content
pnpm generate:offline-media-manifest
pnpm content:lint

MIT áp dụng cho source code và documentation do dự án tạo. Nó không tự động cấp quyền cho audio, exam material, third-party assets hoặc review-only learning content. Xem NOTICE.md và content/licenses/manifest.md.

Package và release

Web và worker images hiện có trên GHCR:

docker pull ghcr.io/jasontm17/ideogram-learning-app/web:v0.1.0-alpha.2
docker pull ghcr.io/jasontm17/ideogram-learning-app/web@sha256:a0f5ba12566ee2a08e249d6189782be24075fcad8996a82b91077dc4cb043926
docker pull ghcr.io/jasontm17/ideogram-learning-app/web:latest
docker pull ghcr.io/jasontm17/ideogram-learning-app/worker:v0.1.0-alpha.2
docker pull ghcr.io/jasontm17/ideogram-learning-app/worker@sha256:e481ec304406ad512a400531469784ed7e36f57cacae630a486f1e3192bf4764
docker pull ghcr.io/jasontm17/ideogram-learning-app/worker:latest

Workflow mới phát hành tag sha-* đầy đủ 40 ký tự; các tag ngắn cũ có thể vẫn tồn tại trên registry. Tag vẫn có thể được đổi trỏ, nên luôn ưu tiên digest sha256:* bất biến khi kiểm chứng/rollback. Bản v0.1.0-alpha.2 là repository/container preview, không phải production deployment. Docker Hub mirror chưa được publish cho release này vì protected credentials không khả dụng; deterministic source tar.gz, SHA256SUMS.txt, social PNG, và project-tour GIF đã được attach. Native EAS builds vẫn chưa được publish. Xem artifact-matrix.md.

Documentation map

Chủ đề	Tài liệu
Tổng quan	Project PDR · Roadmap · Codebase summary
Kiến trúc	System architecture · ADRs · Code standards
Learning	Learning engine · Review/sync · Offline sync
Trust	Security/privacy · Auth · Data lifecycle
Operations	Deployment · Runbooks · Release evidence
AI/content	AI safety · Content governance · Offline media

Roadmap còn mở

• Real-device BackgroundTask và native build/release pipeline.
• Approved audio, checksum registry và browser/device playback proof.
• Hosted web/worker/database, observability, restore và rollback drills.
• Browser/device cross-account E2E, accessibility, and release product gates.
• Grounded/SSE tutor, durable history, broader evaluators và admin workflows.

Cộng tác và chính sách

Contributing · Security · Code of Conduct · Changelog · License · Asset notice

Copyright © 2026 Nguyen Tien Son. Project-authored source and documentation are available under the MIT License, subject to the exclusions described in NOTICE.md.