# naos2w/naosledge architecture

> Architecture diagram of the GitHub repository naos2w/naosledge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naos2w/naosledge
- Repository: https://github.com/naos2w/naosledge

## Overview

Naosledge 是繁體中文公開學習部落格，並提供站長專用 Studio、私人 Vault、Knowledge Atlas 與 Obsidian 手動互通。主要流程是訪客瀏覽已發布文章；站長登入後管理文章或存取私人筆記，並可手動匯入 Obsidian 快照逐篇審查。README 明確指出 Obsidian 真正雙向同步及自動同步尚未啟用。部分連線依 README 或 SOURCE INDEX 建模；未抽樣的來源不推定其內部呼叫。

Main entry points: [`lib/auth.ts`](https://github.com/naos2w/naosledge/blob/main/lib/auth.ts) (管理員授權), [`components/vault-manual-sync-review.tsx`](https://github.com/naos2w/naosledge/blob/main/components/vault-manual-sync-review.tsx) (快照與逐篇審查), [`lib/posts.ts`](https://github.com/naos2w/naosledge/blob/main/lib/posts.ts) (公開文章資料), [`lib/obsidian-m8-windows-agent-controller.ts`](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-windows-agent-controller.ts) (Windows 唯讀代理)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["公開閱讀"]
  node_home["文章索引<br/>[page.tsx]"]
  node_posts["公開文章資料<br/>[posts.ts]"]
  node_data["資料存取邊界<br/>[server.ts]"]
  node_article["文章閱讀<br/>[page.tsx]"]
  node_seo["搜尋與 SEO<br/>[seo.ts]"]
end

subgraph group_studio["站長與認證"]
  node_login["站長登入<br/>[page.tsx]"]
  node_auth["管理員授權<br/>[auth.ts]"]
  node_neon["Neon Auth 與資料 API<br/>[clients.ts]"]
  node_release["正式環境閘門"]
  node_studio["文章工作室<br/>[page.tsx]"]
  node_editor["文章編輯器<br/>[studio-editor.tsx]"]
end

subgraph group_vault["私人知識庫"]
  node_vault["私人 Vault<br/>[vault-server.ts]"]
  node_vaultpage["筆記頁面<br/>[page.tsx]"]
  node_atlas["Knowledge Atlas<br/>[page.tsx]"]
  node_links["Wiki 關係<br/>[wiki-links.ts]"]
end

subgraph group_obsidian["Obsidian 互通"]
  node_syncpage["手動同步審查頁<br/>[page.tsx]"]
  node_review["快照與逐篇審查"]
  node_reviewlogic["審查決策"]
  node_plan["同步差異計畫"]
  node_agent["Windows 唯讀代理"]
  node_baseline["正式基線日誌"]
  node_readonly["唯讀同步主機"]
end

node_visitor(("訪客"))
node_owner(("站長"))
node_obsidian[("Obsidian Vault")]

node_visitor -->|"瀏覽"| node_home
node_home -->|"載入文章"| node_posts
node_posts -->|"讀取公開文章"| node_data
node_data -->|"選用 Neon"| node_neon
node_data -.->|"回退 Supabase"| node_neon
node_visitor -->|"閱讀"| node_article
node_article -->|"載入已發布文章"| node_posts
node_article -->|"產生文章中繼資料"| node_seo
node_owner -->|"登入"| node_login
node_login -->|"檢查管理員"| node_auth
node_auth -->|"驗證 Neon 身分"| node_neon
node_auth -.->|"檢查正式閘門"| node_release
node_owner -->|"管理文章"| node_studio
node_studio -->|"開啟編輯器"| node_editor
node_editor -.->|"儲存文章"| node_posts
node_owner -->|"管理私人筆記"| node_vaultpage
node_vaultpage -->|"載入筆記"| node_vault
node_vault -->|"要求管理員授權"| node_auth
node_vaultpage -->|"解析筆記連結"| node_links
node_owner -->|"探索知識圖譜"| node_atlas
node_atlas -->|"取得圖譜資料"| node_vault
node_owner -->|"手動審查"| node_syncpage
node_syncpage -->|"呈現審查介面"| node_review
node_review -->|"解析與編列意圖"| node_reviewlogic
node_review -->|"建立差異計畫"| node_plan
node_obsidian -->|"手動提供快照"| node_review
node_agent -->|"檢查基線"| node_baseline
node_agent -->|"啟動唯讀主機"| node_readonly
node_agent -.->|"唯讀監看"| node_obsidian

click node_home "https://github.com/naos2w/naosledge/blob/main/app/page.tsx"
click node_posts "https://github.com/naos2w/naosledge/blob/main/lib/posts.ts"
click node_data "https://github.com/naos2w/naosledge/blob/main/lib/data/server.ts"
click node_article "https://github.com/naos2w/naosledge/blob/main/app/notes/%5Bslug%5D/page.tsx"
click node_seo "https://github.com/naos2w/naosledge/blob/main/lib/seo.ts"
click node_login "https://github.com/naos2w/naosledge/blob/main/app/login/page.tsx"
click node_auth "https://github.com/naos2w/naosledge/blob/main/lib/auth.ts"
click node_neon "https://github.com/naos2w/naosledge/blob/main/lib/neon/clients.ts"
click node_release "https://github.com/naos2w/naosledge/blob/main/lib/neon/production-release.ts"
click node_studio "https://github.com/naos2w/naosledge/blob/main/app/studio/page.tsx"
click node_editor "https://github.com/naos2w/naosledge/blob/main/components/studio-editor.tsx"
click node_vault "https://github.com/naos2w/naosledge/blob/main/lib/vault-server.ts"
click node_vaultpage "https://github.com/naos2w/naosledge/blob/main/app/vault/%5Bid%5D/page.tsx"
click node_atlas "https://github.com/naos2w/naosledge/blob/main/app/vault/graph/page.tsx"
click node_links "https://github.com/naos2w/naosledge/blob/main/lib/wiki-links.ts"
click node_syncpage "https://github.com/naos2w/naosledge/blob/main/app/vault/sync/page.tsx"
click node_review "https://github.com/naos2w/naosledge/blob/main/components/vault-manual-sync-review.tsx"
click node_reviewlogic "https://github.com/naos2w/naosledge/blob/main/lib/obsidian-manual-sync-review.ts"
click node_plan "https://github.com/naos2w/naosledge/blob/main/lib/obsidian-sync-plan.ts"
click node_agent "https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-windows-agent-controller.ts"
click node_baseline "https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-production-baseline-journal.ts"
click node_readonly "https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-readonly-host.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_posts,node_data,node_article,node_seo toneBlue
class node_login,node_auth,node_neon,node_release,node_studio,node_editor,node_obsidian toneAmber
class node_vault,node_vaultpage,node_atlas,node_links toneMint
class node_syncpage,node_review,node_reviewlogic,node_plan,node_agent,node_baseline,node_readonly toneRose
class node_visitor,node_owner toneIndigo
```

## Components

### 公開閱讀

- [文章索引](https://github.com/naos2w/naosledge/blob/main/app/page.tsx): `app/page.tsx`
- [公開文章資料](https://github.com/naos2w/naosledge/blob/main/lib/posts.ts): `lib/posts.ts`
- [資料存取邊界](https://github.com/naos2w/naosledge/blob/main/lib/data/server.ts): `lib/data/server.ts`
- [文章閱讀](https://github.com/naos2w/naosledge/blob/main/app/notes/%5Bslug%5D/page.tsx): `app/notes/[slug]/page.tsx`
- [搜尋與 SEO](https://github.com/naos2w/naosledge/blob/main/lib/seo.ts): `lib/seo.ts`

### 站長與認證

- [站長登入](https://github.com/naos2w/naosledge/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [管理員授權](https://github.com/naos2w/naosledge/blob/main/lib/auth.ts): `lib/auth.ts`
- [Neon Auth 與資料 API](https://github.com/naos2w/naosledge/blob/main/lib/neon/clients.ts): `lib/neon/clients.ts`
- [正式環境閘門](https://github.com/naos2w/naosledge/blob/main/lib/neon/production-release.ts): `lib/neon/production-release.ts`
- [文章工作室](https://github.com/naos2w/naosledge/blob/main/app/studio/page.tsx): `app/studio/page.tsx`
- [文章編輯器](https://github.com/naos2w/naosledge/blob/main/components/studio-editor.tsx): `components/studio-editor.tsx`

### 私人知識庫

- [私人 Vault](https://github.com/naos2w/naosledge/blob/main/lib/vault-server.ts): `lib/vault-server.ts`
- [筆記頁面](https://github.com/naos2w/naosledge/blob/main/app/vault/%5Bid%5D/page.tsx): `app/vault/[id]/page.tsx`
- [Knowledge Atlas](https://github.com/naos2w/naosledge/blob/main/app/vault/graph/page.tsx): `app/vault/graph/page.tsx`
- [Wiki 關係](https://github.com/naos2w/naosledge/blob/main/lib/wiki-links.ts): `lib/wiki-links.ts`

### Obsidian 互通

- [手動同步審查頁](https://github.com/naos2w/naosledge/blob/main/app/vault/sync/page.tsx): `app/vault/sync/page.tsx`
- [快照與逐篇審查](https://github.com/naos2w/naosledge/blob/main/components/vault-manual-sync-review.tsx): `components/vault-manual-sync-review.tsx`
- [審查決策](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-manual-sync-review.ts): `lib/obsidian-manual-sync-review.ts`
- [同步差異計畫](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-sync-plan.ts): `lib/obsidian-sync-plan.ts`
- [Windows 唯讀代理](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-windows-agent-controller.ts): `lib/obsidian-m8-windows-agent-controller.ts`
- [正式基線日誌](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-production-baseline-journal.ts): `lib/obsidian-m8-production-baseline-journal.ts`
- [唯讀同步主機](https://github.com/naos2w/naosledge/blob/main/lib/obsidian-m8-readonly-host.ts): `lib/obsidian-m8-readonly-host.ts`

### Other components

- **訪客**
- **站長**
- **Obsidian Vault**

## Connections

- 訪客 → 文章索引: 瀏覽
- 文章索引 → 公開文章資料: 載入文章 (evidence: `app/page.tsx`)
- 公開文章資料 → 資料存取邊界: 讀取公開文章 (evidence: `lib/posts.ts`)
- 資料存取邊界 → Neon Auth 與資料 API: 選用 Neon (evidence: `lib/data/server.ts`)
- 資料存取邊界 → Neon Auth 與資料 API: 回退 Supabase (evidence: `lib/data/server.ts`)
- 訪客 → 文章閱讀: 閱讀
- 文章閱讀 → 公開文章資料: 載入已發布文章 (evidence: `app/notes/[slug]/page.tsx`)
- 文章閱讀 → 搜尋與 SEO: 產生文章中繼資料 (evidence: `app/notes/[slug]/page.tsx`)
- 站長 → 站長登入: 登入
- 站長登入 → 管理員授權: 檢查管理員 (evidence: `app/login/page.tsx`)
- 管理員授權 → Neon Auth 與資料 API: 驗證 Neon 身分 (evidence: `lib/auth.ts`)
- 管理員授權 → 正式環境閘門: 檢查正式閘門 (evidence: `lib/auth.ts`)
- 站長 → 文章工作室: 管理文章
- 文章工作室 → 文章編輯器: 開啟編輯器 (evidence: `app/studio/page.tsx`)
- 文章編輯器 → 公開文章資料: 儲存文章 (evidence: `components/studio-editor.tsx`)
- 站長 → 筆記頁面: 管理私人筆記
- 筆記頁面 → 私人 Vault: 載入筆記 (evidence: `app/vault/[id]/page.tsx`)
- 私人 Vault → 管理員授權: 要求管理員授權 (evidence: `lib/vault-server.ts`)
- 筆記頁面 → Wiki 關係: 解析筆記連結 (evidence: `app/vault/[id]/page.tsx`)
- 站長 → Knowledge Atlas: 探索知識圖譜
- Knowledge Atlas → 私人 Vault: 取得圖譜資料 (evidence: `app/vault/graph/page.tsx`)
- 站長 → 手動同步審查頁: 手動審查
- 手動同步審查頁 → 快照與逐篇審查: 呈現審查介面 (evidence: `app/vault/sync/page.tsx`)
- 快照與逐篇審查 → 審查決策: 解析與編列意圖 (evidence: `components/vault-manual-sync-review.tsx`)
- 快照與逐篇審查 → 同步差異計畫: 建立差異計畫 (evidence: `components/vault-manual-sync-review.tsx`)
- Obsidian Vault → 快照與逐篇審查: 手動提供快照
- Windows 唯讀代理 → 正式基線日誌: 檢查基線 (evidence: `lib/obsidian-m8-windows-agent-controller.ts`)
- Windows 唯讀代理 → 唯讀同步主機: 啟動唯讀主機 (evidence: `lib/obsidian-m8-windows-agent-controller.ts`)
- Windows 唯讀代理 → Obsidian Vault: 唯讀監看