Kiến trúc hệ thống

Tài liệu này mô tả toàn bộ luồng xử lý của hệ thống Notes, bao gồm 3 luồng chính:

1. Luồng Build — từ source code đến trang web public
2. Luồng Edit — chỉnh sửa nội dung qua Decap CMS
3. Luồng Comment — người đọc bình luận qua Giscus

---

Tổng quan thành phần

Thành phần	Vai trò
linhlvit/notes	Repo GitHub private — chứa toàn bộ source .md
linhlvit/notes-comments	Repo GitHub public — chứa GitHub Discussions để nhận comment
Cloudflare Pages notes-8t9.pages.dev	Host static site được build từ MkDocs
Cloudflare Worker notes-oauth.linhlv-it.workers.dev	OAuth proxy — đứng giữa Decap CMS và GitHub OAuth
GitHub OAuth App OAuth Note Cloudflares	Xác thực quyền truy cập repo khi dùng Decap CMS
Decap CMS /admin	Giao diện CMS trên trình duyệt để tạo/sửa file .md
Giscus	Hệ thống comment nhúng vào mỗi trang, dùng GitHub Discussions

---

Luồng 1 — Build & Deploy

Khi bạn push code lên GitHub, Cloudflare Pages tự động build và deploy.

sequenceDiagram
    actor Owner as Bạn (Owner)
    participant Local as Local Machine
    participant GitHub as GitHub<br/>linhlvit/notes (private)
    participant CF_Pages as Cloudflare Pages<br/>notes-8t9.pages.dev

    Owner->>Local: Viết/sửa file .md
    Owner->>Local: git push origin main
    Local->>GitHub: Push source code (.md, mkdocs.yml, requirements.txt)
    GitHub-->>CF_Pages: Trigger build webhook
    CF_Pages->>CF_Pages: pip install -r requirements.txt
    CF_Pages->>CF_Pages: mkdocs build → /site
    CF_Pages-->>Owner: Deploy thành công<br/>https://notes-8t9.pages.dev

---

Luồng 2 — Edit qua Decap CMS

Khi bạn muốn tạo hoặc sửa nội dung qua giao diện web tại /admin.

sequenceDiagram
    actor Owner as Bạn (Owner)
    participant Admin as Decap CMS<br/>/admin
    participant Worker as Cloudflare Worker<br/>notes-oauth.linhlv-it.workers.dev
    participant GH_OAuth as GitHub OAuth App<br/>OAuth Note Cloudflares
    participant GitHub as GitHub API<br/>linhlvit/notes (private)
    participant CF_Pages as Cloudflare Pages<br/>notes-8t9.pages.dev

    Owner->>Admin: Vào notes-8t9.pages.dev/admin
    Admin->>Admin: Load config.yml + decap-cms.js
    Owner->>Admin: Click "Login with GitHub"
    Admin->>Worker: Popup → GET /auth
    Worker->>GH_OAuth: Redirect đến GitHub OAuth authorize
    GH_OAuth->>Owner: Hiện trang "Authorize linhlvit"
    Owner->>GH_OAuth: Click "Authorize"
    GH_OAuth->>Worker: Redirect callback?code=xxx
    Worker->>GH_OAuth: POST exchange code → access_token
    GH_OAuth-->>Worker: Trả về access_token
    Worker->>Admin: postMessage "authorization:github:success:{token}"
    Admin->>Admin: Lưu token, load danh sách collections
    Admin->>GitHub: GET /repos/linhlvit/notes (dùng token)
    GitHub-->>Admin: Trả về danh sách file .md
    Owner->>Admin: Tạo/sửa nội dung
    Admin->>GitHub: PUT commit file .md mới lên branch main
    GitHub-->>CF_Pages: Trigger build webhook
    CF_Pages->>CF_Pages: mkdocs build lại
    CF_Pages-->>Owner: Trang web cập nhật

---

Luồng 3 — Comment (Giscus)

Khi người đọc muốn bình luận trên một trang bất kỳ.

sequenceDiagram
    actor Reader as Người đọc
    participant Site as Cloudflare Pages<br/>notes-8t9.pages.dev
    participant Giscus as Giscus Widget
    participant GH_Discuss as GitHub Discussions<br/>linhlvit/notes-comments (public)

    Reader->>Site: Vào xem một trang bất kỳ
    Site->>Site: Load trang HTML + Giscus script
    Site->>Giscus: Load iframe Giscus<br/>(repo: notes-comments, mapping: pathname)
    Giscus->>GH_Discuss: GET discussions theo pathname của trang
    GH_Discuss-->>Giscus: Trả về danh sách comment
    Giscus-->>Reader: Hiện box comment cuối trang
    Reader->>Giscus: Nhập comment, click gửi
    Giscus->>Reader: Redirect đăng nhập GitHub (nếu chưa login)
    Reader->>Giscus: Đã xác thực GitHub
    Giscus->>GH_Discuss: POST tạo comment mới trong Discussion
    GH_Discuss-->>Giscus: Xác nhận thành công
    Giscus-->>Reader: Hiện comment vừa gửi

---

Sơ đồ tổng thể

graph TD
    subgraph LOCAL["💻 Local"]
        MD["docs/**/*.md"]
        YML["mkdocs.yml"]
    end

    subgraph GITHUB["🐙 GitHub"]
        REPO_PRIVATE["linhlvit/notes<br/>🔒 Private"]
        REPO_PUBLIC["linhlvit/notes-comments<br/>🔓 Public<br/>(Discussions)"]
        OAUTH_APP["GitHub OAuth App"]
    end

    subgraph CLOUDFLARE["☁️ Cloudflare"]
        CF_PAGES["Cloudflare Pages<br/>notes-8t9.pages.dev"]
        CF_WORKER["Cloudflare Worker<br/>notes-oauth.linhlv-it.workers.dev"]
    end

    subgraph BROWSER["🌐 Browser"]
        SITE["Static Site<br/>(MkDocs Material)"]
        ADMIN["Decap CMS<br/>/admin"]
        GISCUS["Giscus Widget"]
    end

    MD --> REPO_PRIVATE
    YML --> REPO_PRIVATE
    REPO_PRIVATE -->|"trigger build"| CF_PAGES
    CF_PAGES -->|"serve"| SITE

    ADMIN -->|"OAuth popup /auth"| CF_WORKER
    CF_WORKER -->|"exchange code"| OAUTH_APP
    CF_WORKER -->|"postMessage token"| ADMIN
    ADMIN -->|"commit .md"| REPO_PRIVATE

    SITE -->|"load iframe"| GISCUS
    GISCUS -->|"read/write discussions"| REPO_PUBLIC

Comments