thangldw.github.io

English · Tiếng Việt · 日本語

A dependency-light portfolio, application catalog, and static application host deployed with GitHub Pages.

%%{init: {"theme":"base","flowchart":{"curve":"basis","nodeSpacing":38,"rankSpacing":58},"themeVariables":{"background":"#F7F7F5","fontFamily":"Inter, Arial, sans-serif","lineColor":"#667085","primaryTextColor":"#172B4D"}}}%%
flowchart LR
    PJ["projects-data.json<br/>project source"]:::yellow --> PL["Runtime catalog<br/>loader"]:::blue
    CM["Certification public<br/>manifest"]:::pink --> PL
    PL --> H["Portfolio home<br/>featured projects"]:::purple
    PL --> A["/apps/<br/>full catalog"]:::green
    CS["Private cert source<br/>+ question banks"]:::orange --> CB["Local production<br/>build"]:::blue
    CB --> CA["/<test>/<br/>generated study shells"]:::cyan
    CB --> CM
    CB --> API["Cloudflare content API<br/>private banks / controlled delivery"]:::orange
    API --> CA
    H --> GP["GitHub Pages"]:::yellow
    A --> GP
    CA --> GP
    classDef yellow fill:#FFF4A3,stroke:#C9A227,stroke-width:2px,color:#172B4D
    classDef blue fill:#D9EAFD,stroke:#4C78A8,stroke-width:2px,color:#172B4D
    classDef pink fill:#FFE1E6,stroke:#C96A7B,stroke-width:2px,color:#172B4D
    classDef purple fill:#E9DDF7,stroke:#8064A2,stroke-width:2px,color:#172B4D
    classDef green fill:#DDF5E3,stroke:#4F9D69,stroke-width:2px,color:#172B4D
    classDef orange fill:#FFE2C3,stroke:#C97A2B,stroke-width:2px,color:#172B4D
    classDef cyan fill:#D9F3F0,stroke:#3B8F87,stroke-width:2px,color:#172B4D

Loading

English

Purpose and operating model

thangldw.github.io is a static personal portfolio and application host. GitHub Pages hosts the static shell; controlled certification content is supplied by external Cloudflare APIs. Root-site maintenance does not require a package-manager build, while generated apps are built in their source repositories. GitHub Pages serves committed HTML, CSS, JavaScript, JSON, fonts, images, and generated application artifacts.

• Production: https://thangldw.github.io/
• Default branch: master
• Runtime: standards-based browser APIs
• Deployment: GitHub Pages from the repository root
• Analytics: shared local script included once on non-redirect pages

Public routes

Route	Responsibility	Source of truth
/	Portfolio profile and selected engineering work	Root HTML plus shared project catalog
/apps/	Application catalog grouped by purpose	js/projects-data.json
/japan-pr-guide/	Standalone permanent-residence planning tool	Route-local static assets
/<test>/	Generated certification study shells	Private thangldw/cert source repository
/jlpt-n1/, /pmp/	Independent N1 skill practice and PMP study	Private cert source and controlled APIs
/ragops/, /proofline/, /awesome-maintainer-defense/, /toolbox/, /kakeflow/	Product introductions	Portfolio shell or canonical product source
/assets/learning/certifications-manifest.json	Public certification metadata and counts	Local certification production build
/case-studies/{flagship}/	Recruiter-facing evidence for four flagship projects	Route-local semantic HTML and shared case-study styles
/404.html	GitHub Pages fallback	Repository source

Every sitemap route must have canonical metadata, a meaningful description, required Open Graph fields, and a valid local social image where applicable.

Shared catalog architecture

js/projects-data.json is the only durable source for project metadata. js/projects-data.js validates and loads it at runtime with revalidation. Both the home page and /apps/ wait for the same readiness promise before rendering.

The loader also reads /assets/learning/certifications-manifest.json. It derives the certification count, names, labels, and collection tags at runtime. Adding a certification therefore does not require manually editing the home page or application catalog.

The public certification manifest is an explicit metadata allowlist. It contains identity, issuer, routes, syllabus and public exam information, but not prompts, choices, answer keys, explanations, domains, glossary content, or learner data. Question banks and JLPT corpora remain in private compilation inputs and Cloudflare storage. Pages ships application shells, not banks or browser decryption keys. Anonymous sessions, quotas, issuance checks and server-side grading bound delivery; visible content remains copyable.

Repository layout

thangldw.github.io/
├── index.html
├── 404.html
├── apps/
│   ├── index.html
│   ├── japan-pr-guide/       # Redirect to /japan-pr-guide/
│   └── cert/                 # Legacy redirects to root study routes
├── assets/learning/          # Generated shared study assets; do not hand-edit
├── japan-pr-guide/           # Generated Japan PR Guide app
├── case-studies/              # Four static flagship evidence narratives
├── assets/                    # Social images and local fonts
│   └── fonts/licenses/        # Upstream font notices and provenance
├── css/                       # Tokens, shared shell, and route styles
├── js/
│   ├── projects-data.json     # Project metadata source of truth
│   ├── projects-data.js       # Runtime loader and schema guard
│   └── shared behavior
├── scripts/                   # Static audits and browser smoke tests
├── robots.txt
└── sitemap.xml

Local development

Requirements:

• Python 3.10 or later
• Node.js 22 or later
• Google Chrome at the standard macOS path, or CHROME_BIN pointing to a compatible executable

No dependency installation is required.

python3 -m http.server 4173

Open http://localhost:4173/. Use a local server rather than opening files directly because runtime JSON loading requires HTTP.

Quality gates

python3 scripts/audit_ui_standards.py
python3 scripts/validate_design_system.py
python3 scripts/validate_site.py
node scripts/test_homepage.mjs
node scripts/smoke_cert.mjs
node scripts/smoke_brand.mjs
node scripts/smoke_product_pages.mjs

Gate	Coverage
UI audit	Shared shell, design tokens, contrast, accessibility conventions, and prohibited presentation debt
Site validator	HTML parsing, local links, Markdown policy, JSON contracts, analytics, sitemap, canonical and social metadata
Browser smoke suite	Project JSON loading, certification manifest propagation, catalog layout, every certification route, theme isolation, exam mode, and responsive behavior

Tests use isolated temporary servers and Chrome profiles and remove them after completion.

Updating projects

Edit only js/projects-data.json.

1. Keep IDs unique and stable.
2. Provide all required catalog fields and a safe destination URL.
3. The home page includes all projects and learning collections in title order (English collation, numeric titles first). Keep featured metadata for other consumers.
4. Run validation and browser smoke tests.
5. Commit and push.

Home preserves the complete one-page profile, working approach, languages, contact links, and selected-project carousel. The full catalog uses compact cards of equal height, search, and group filters for Engineering, Utilities, Learning, and Experiments via catalogGroup. catalogDescription optionally supplies concise catalog copy. Email contacts use mailto:. Shared click events record only fixed project IDs and page locations.

Do not duplicate project descriptions in index.html or apps/index.html. The JSON loader uses cache: "no-store", so content updates do not require changing HTML cache keys. Loader/schema cache keys change only when loader behavior changes.

Support dialog and asset provenance

The portfolio home includes an optional Support dialog. GitHub Sponsors opens an external confirmation flow, Ko-fi opens an external support link, and Vietnamese bank support uses the local assets/support-vietqr-mb.jpg image. Keep payment destinations explicit, never collect payment credentials in this static site, and verify the QR destination before every release that changes the image.

Self-hosted font provenance and upstream license texts live under assets/fonts/licenses/. scripts/validate_site.py permits only these durable license documents plus the root README; temporary Markdown reports and QA screenshots must stay outside the repository.

Publishing Certification Library

The private thangldw/cert repository owns certification manifests, question banks, application code, and build scripts.

1. In the source repository, run npm ci, data validation, tests, and npm run build.
2. Inspect dist/client/certifications-manifest.json and confirm it contains metadata only.
3. Use the source release helper to synchronize dist/client/ into /assets/learning/ and root study routes, the standalone N1 shell to /jlpt-n1/, and legacy redirects. PMP has its own /pmp/ build/release helper. Deploy the content API before publishing shells when content changes.
4. Preserve required site integration layers such as analytics and shared styling when the release process applies them.
5. Run all website quality gates.
6. Push the source repository before the generated website artifact.
7. Wait for GitHub Pages to report built, then verify the hub and representative child routes.

The local certification build creates canonical child routes and updates the manifest automatically. GitHub Actions are not required. A deliberate local build and deployment are still required.

Deployment and rollback

1. Start from a clean working tree and review all generated changes.
2. Run every relevant quality gate.
3. Commit a focused change and push master.
4. Monitor GitHub Pages until its state is built.
5. Verify production HTML, JSON responses, and critical rendered content.

Do not silently replace generated assets in an unrelated commit. If production is broken, revert the focused commit or publish a corrective commit, rerun validation, and verify deployment again. Avoid force pushes.

Security and privacy

• Never commit secrets, credentials, private datasets, learner backups, or machine-specific paths.
• Keep fonts and production assets local; external font dependencies are rejected.
• Validate all JSON before rendering and escape catalog text inserted into HTML.
• Keep question banks out of Pages; controlled content requires network access. Browser-visible material remains copyable.
• Certification learner data remains in browser storage; the website does not collect or synchronize it.
• Analytics must not run on redirect pages and must appear exactly once elsewhere.

Contribution policy

Keep changes route-focused, accessible, responsive, and independently verifiable. Shared visual behavior belongs in tokens or shared styles rather than inline presentation. New routes require sitemap, canonical, Open Graph, social-image, analytics, validation, and smoke-test updates.

Tiếng Việt

Mục đích và mô hình vận hành

thangldw.github.io là portfolio và host ứng dụng tĩnh. Pages host shell tĩnh; nội dung chứng chỉ được API Cloudflare bên ngoài cấp có kiểm soát. Root website không cần bước build bằng package manager; app đã sinh được build tại repo source riêng. GitHub Pages phục vụ trực tiếp HTML, CSS, JavaScript, JSON, font, ảnh và artifact ứng dụng đã sinh.

• Production: https://thangldw.github.io/
• Default branch: master
• Runtime: API chuẩn của trình duyệt
• Deploy: GitHub Pages từ root repository

Route công khai

Route	Trách nhiệm	Nguồn chuẩn
/	Portfolio và Side Projects tiêu biểu	Root HTML và catalog project dùng chung
/apps/	Danh mục ứng dụng có search/filter	js/projects-data.json
/japan-pr-guide/	Công cụ lập kế hoạch thường trú	Static asset riêng của route
/cert/	Certification Library đã build	Repo private thangldw/cert
/jlpt-n1/, /pmp/	Luyện N1 theo kỹ năng và PMP độc lập	Source cert private và API có kiểm soát
Certification manifest	Metadata và count công khai	Local production build của repo cert
/case-studies/{flagship}/	Bằng chứng recruiter-facing cho bốn flagship	Semantic HTML theo route và CSS dùng chung
/404.html	Fallback của GitHub Pages	Source repository

Mọi route trong sitemap phải có canonical, description, Open Graph và social image hợp lệ khi cần.

Kiến trúc catalog dùng chung

js/projects-data.json là nguồn duy nhất cho metadata project. Loader kiểm tra và fetch JSON ở runtime; trang chủ và /apps/ cùng chờ một readiness promise trước khi render.

Loader đồng thời đọc public certification manifest để tự tính số lượng, tên, label và tag của collection. Vì vậy thêm chứng chỉ không cần sửa thủ công trang chủ hoặc application catalog.

Manifest chứng chỉ chỉ dùng allowlist metadata công khai: định danh, issuer, route, syllabus và thông tin kỳ thi. Nó không chứa prompt, choice, đáp án, giải thích, domain, glossary hoặc dữ liệu người học. Question bank và corpus JLPT nằm trong nguồn build private và storage Cloudflare. Pages chỉ chứa shell, không chứa bank hoặc khóa giải mã trình duyệt. Session ẩn danh, quota, kiểm tra issuance và chấm phía server kiểm soát cấp nội dung; nội dung đã hiển thị vẫn có thể sao chép.

Cấu trúc và phát triển local

Dùng cây thư mục ở phần English. cert/ là generated artifact, không sửa bundle thủ công. Cần Python 3.10+, Node.js 22+ và Chrome. Không cần cài dependency.

python3 -m http.server 4173

Mở http://localhost:4173/. Phải dùng HTTP server vì browser fetch JSON ở runtime.

Cổng chất lượng

Chạy UI audit, site validator và browser smoke suite bằng các command trong phần English. Các gate kiểm tra shared shell, token/contrast/accessibility, link và metadata, contract JSON, analytics, sitemap, project loader, certification manifest, mọi route chứng chỉ, theme, exam mode và responsive layout.

Cập nhật project

Chỉ sửa js/projects-data.json. Giữ ID duy nhất/ổn định, khai báo đủ field và URL an toàn, dùng featured cùng featuredOrder cho trang chủ, sau đó chạy validation/smoke test và push. Không copy description vào HTML. Content JSON dùng cache: "no-store", nên không cần đổi cache key HTML mỗi lần.

Support và nguồn gốc asset

Trang chủ có dialog Support tùy chọn. GitHub Sponsors mở luồng xác nhận bên ngoài, Ko-fi dùng liên kết hỗ trợ bên ngoài, và chuyển khoản Việt Nam dùng ảnh local assets/support-vietqr-mb.jpg. Website tĩnh không thu thập thông tin thanh toán. Phải xác minh người nhận QR trước mỗi release thay đổi ảnh. Hồ sơ nguồn và license font tự host nằm trong assets/fonts/licenses/; report Markdown và ảnh QA tạm không được commit.

Publish Certification Library

Repo private thangldw/cert quản lý dữ liệu, question bank, application code và build:

1. Chạy npm ci, validation, test và production build.
2. Kiểm tra public manifest chỉ có metadata.
3. Dùng release helper đồng bộ dist/client/ sang /cert/, shell N1 sang /jlpt-n1/ và redirect cũ. PMP có helper build/release riêng tại /pmp/. Deploy content API trước shell khi nội dung thay đổi.
4. Giữ các integration layer cần thiết của website.
5. Chạy toàn bộ quality gate của website.
6. Push source repo trước generated artifact.
7. Chờ GitHub Pages báo built rồi kiểm tra production.

Build local tự tạo route và manifest; không cần GitHub Actions. Tuy nhiên vẫn cần build, review và deploy có chủ đích.

Deploy, bảo mật và đóng góp

Luôn bắt đầu từ working tree sạch, kiểm tra generated diff, chạy test, commit tập trung, push master, chờ Pages deploy và xác minh HTML/JSON/UI production. Nếu lỗi, revert commit tập trung hoặc tạo corrective commit; không force-push.

Không commit secret, credential, private dataset, learner backup hoặc đường dẫn máy. Font và asset phải local. JSON phải được validate và text phải escape trước khi chèn HTML. Bank không được deploy lên Pages; API cần kết nối mạng và nội dung đã hiển thị vẫn có thể sao chép. Dữ liệu học nằm trong browser storage và không được website đồng bộ.

Thay đổi cần tập trung theo route, accessible, responsive và test được. Route mới phải cập nhật sitemap, canonical, Open Graph, social image, analytics, validation và smoke test.

日本語

Purpose と operating model

thangldw.github.io は static portfolio と application host です。Pages は static shell を host し、証明書学習 content は外部 Cloudflare API が制御して配信します。Root site 自体は package-manager build 不要ですが、generated app は各 source repo で build します。GitHub Pages が committed HTML、CSS、JavaScript、JSON、font、image、generated artifact を配信します。

• Production: https://thangldw.github.io/
• Default branch: master
• Runtime: standard browser API
• Deployment: repository root から GitHub Pages

Public route

Route	Responsibility	Source of truth
/	Portfolio と featured project	Root HTML と shared project catalog
/apps/	Search/filter 可能な application catalog	js/projects-data.json
/japan-pr-guide/	永住計画 tool	Route-local static asset
/<test>/	Generated certification study shells	Private thangldw/cert repo
/jlpt-n1/, /pmp/	独立した N1 skill practice と PMP study	Private cert source と controlled API
Certification manifest	Public metadata と count	Cert local production build
/case-studies/{flagship}/	4 flagship の recruiter-facing evidence	Route-local semantic HTML と shared CSS
/404.html	GitHub Pages fallback	Repository source

Sitemap route には canonical、description、Open Graph、必要な social image を設定します。

Shared catalog architecture

js/projects-data.json が project metadata の唯一の source です。Loader が runtime に validation/fetch し、home page と /apps/ は同じ readiness promise 後に render します。

Loader は public certification manifest も読み、certification count、name、label、tag を自動生成します。Certification 追加時に home page や application catalog を手動編集する必要はありません。

Certification manifest は identity、issuer、route、syllabus、public exam metadata の allowlist だけです。Prompt、choice、answer、explanation、domain、glossary、learner data を含まず、question bank と JLPT corpus は private build input と Cloudflare storage に保持します。Pages は shell のみを配信し、bank や browser decryption key を含めません。Anonymous session、quota、issuance check、server-side grading で配信を制御しますが、表示済み content はコピー可能です。

Local development と quality gate

English セクションの directory tree を参照してください。cert/ は generated artifact で、bundle を直接編集しません。Python 3.10+、Node.js 22+、Chrome が必要です。Dependency install は不要です。

python3 -m http.server 4173
python3 scripts/audit_ui_standards.py
python3 scripts/validate_site.py
node scripts/smoke_cert.mjs

JSON runtime loading のため file を直接開かず HTTP server を使います。Quality gate は shared shell、token、contrast、accessibility、link、metadata、JSON contract、analytics、sitemap、catalog loading、manifest propagation、全 certification route、theme、exam mode、responsive behavior を確認します。

Project と certification の更新

Project metadata は js/projects-data.json だけで編集します。Stable unique ID、required field、安全な URL、featured/featuredOrder を設定し、test 後に push します。JSON content update のたびに HTML cache key を変える必要はありません。

Certification は private thangldw/cert repo で data validation、test、production build を行い、metadata-only manifest を確認して source release helper で /cert/、/jlpt-n1/ と legacy redirect を同期します。PMP は /pmp/ 専用 helper を使用します。Content 変更時は shell 公開前に API を deploy します。Website gate 後、source repo、generated artifact の順に push し、Pages が built になったら production を検証します。GitHub Actions は不要ですが intentional local build/deploy は必要です。

Home の optional Support dialog は external GitHub Sponsors flow、external Ko-fi support link、local VietQR asset を使用します。Static site は payment credential を収集しません。QR image を変更する release では recipient を検証します。Self-hosted font の provenance と upstream license は assets/fonts/licenses/ に保存し、temporary report と QA screenshot は repository に commit しません。

Deployment、security、contribution

Clean working tree、generated diff review、全 test、focused commit、master push、Pages completion、production HTML/JSON/UI verification の順で進めます。障害時は focused revert または corrective commit を使い、force-push を避けます。

Secret、credential、private dataset、learner backup、machine-specific path を commit しません。Font/asset は local に置き、JSON を validate し、HTML 挿入前に text を escape します。Bank は Pages に配置しません。API content は network 接続を必要とし、表示済み content のコピーを防止する保証はありません。Learner data は browser storage 内に留まります。

変更は route-focused、accessible、responsive、independently verifiable にします。新 route では sitemap、canonical、Open Graph、social image、analytics、validation、smoke test を更新します。

Canonical homepage design — 2026-10-10

The approved homepage is the design reference for future /apps/ and /cert/ updates. Those routes retain their current implementation in this release; generated /cert/ changes must be made in its source repository.

• Visual register: minimal portfolio, restrained separators, no decorative cards.
• Light default on every homepage load; dark mode is an explicit user action. Use the shared site-shell.js theme control and themechange event.
• Canonical runtime token owner: css/tokens.css; shared recipes: css/site-shell.css; full contract: DESIGN.md. Light: canvas #f6f5f1, text #23291f, muted #535e4b, accent #965025, border #d1d7c9, controls #e9ede3. Dark: canvas #11150e, text #e5e6df, muted #b9bdb5, accent #e69d6b, border #32382d, controls #20261c. Home and Apps consume the same tokens; generated Cert receives shared shell and catalog aliases through the existing integration stylesheet.
• Typography: self-hosted Inter for Latin scripts; Japanese and Chinese use script-capable system stacks. Desktop main body stays at 14px for the explicit single-screen requirement, with 16px mobile prose. No clipped content or forced hidden document overflow.
• Layout: sidebar plus fluid main column, compact spacing at short desktop heights. About paragraphs fill the available column and wrap naturally. At wider screens the frame grows to 1800px. Mobile reflows vertically.
• Language: EN/VN/JP/CN buttons; English default, locale applies to owned copy, project descriptions, accessibility labels, contact feedback, and document language. Proper names remain unchanged. Japanese uses consistent polite prose; Chinese uses Simplified Chinese. This is a global technical portfolio with multilingual support, not a Japan-only regulated service.
• Project source: existing shared catalog and certification-manifest loader. All entries appear A–Z with circular manual navigation; no autoplay. The renderer shows three cards on desktop, two on tablet, one on mobile; arrows and keyboard navigation wrap in both directions.
• Contact: an accessible native dialog with Copy email, Gmail compose, and portable mailto options. Email composition is user-triggered.
• Cross-route adoption: reuse these semantic colors, typography, brand, theme, language, focus, and spacing contracts when adapting /apps/ and the /cert/ source. Preserve route-specific information architecture and application behavior.

Homepage runtime files are index.html, css/homepage.css, js/homepage.js, js/home-locales.mjs, and js/home-project-order.mjs. No production package installation or build is required.

Technical standardization is enforced by scripts/validate_design_system.py, also invoked by the site validator. It checks light/dark token/document drift, typography and palette literals in native route CSS, shared logo/control states, and Home/Apps/Cert integration. Generated assessment internals retain their source-owned styles until that workflow is migrated; generated bundles are never edited by the portfolio release.

Official CSS entry point: css/site-shell.css → css/tokens.css. Every public route inherits this foundation; page CSS owns composition. Core token redefinition anywhere in authored css/ is rejected by the design validation gate. See mandatory inheritance contract.

Unified learning catalog

/apps/ lists every certification from the public metadata manifest, retaining curated descriptions for existing projects and avoiding duplicate destinations. Certification tests use /<slug>/; the approved legacy /cert/<slug>/ URLs are forwarded through the Pages 404 handler, while the /cert directory is removed. The migration keeps stable IDs, local progress and content API contracts intact. New releases must synchronize shared assets and every study shell from one source build.