Skip to content
ภาพรวมสถาปัตยกรรม

ภาพรวมสถาปัตยกรรม · Architecture overview

View raw
On this page

NVX Stack Builder เป็นแอป Next.js 16.4 (App Router, React 19.3, TypeScript, Tailwind v4) ที่ เกือบทั้งหมดทำงานฝั่ง client มี endpoint ฝั่งเซิร์ฟเวอร์เพียงตัวเดียวคือ /api/plan และ deploy เป็น Cloudflare Worker ผ่าน OpenNext adapter (@opennextjs/cloudflare) ตั้งแต่ v0.3.0

หลักการออกแบบ#

  1. Data-driven เทมเพลตเป็นข้อมูล การประกอบคำสั่งเป็นฟังก์ชันบริสุทธิ์ (pure function) ทดสอบได้โดยไม่ต้องมีเบราว์เซอร์
  2. Client-first, stateless server การประกอบคำสั่ง สร้างสคริปต์ zip และลิงก์แชร์ทำในเบราว์เซอร์ เซิร์ฟเวอร์ไม่มีฐานข้อมูล ไม่มี session ไม่มีบัญชีผู้ใช้
  3. Text-only commands ไม่มีการรันคำสั่งที่ใดเลย (ดู safety-model)
  4. Graceful degradation AI ล้มเหลวเมื่อไร ใช้ rule-based planner แทนเสมอ; rate-limit binding ใช้ไม่ได้ ใช้ in-memory แทน
  5. Prerendered pages ทุกหน้า prerender ตอน build (cacheComponents: true) Worker จึงเสิร์ฟ static assets เป็นหลัก

แผนภาพระบบ#

Mermaid diagram (source below)
Mermaid source
flowchart LR
  subgraph Browser["เบราว์เซอร์ (client)"]
    UI["Pages & components<br/>src/app, src/components"]
    Builder["Builder state<br/>BuilderConfig + BuilderEdits"]
    Composer["composer.ts<br/>placeholders.ts"]
    Scripts["scripts.ts / download.ts<br/>setup.sh, setup.ps1, zip"]
    Share["share.ts<br/>#s= token"]
    LS[("localStorage<br/>nvx-builder-state, nvx-lang, nvx-theme")]
  end
  subgraph Worker["Cloudflare Worker: nvx-stack-builder"]
    Assets["ASSETS binding<br/>prerendered HTML/JS/CSS"]
    API["/api/plan route.ts"]
    RL["Rate limit bindings<br/>NVX_PLAN_LIMITER / NVX_PLAN_AI_LIMITER"]
    Fallback["fallback.ts (rule-based)"]
  end
  OpenAI[("OpenAI Responses API")]
  Data["src/data/templates<br/>(bundled into client + server)"]

  UI --> Builder --> Composer --> Scripts
  Builder <--> Share
  Builder <--> LS
  Data --> Composer
  UI -- "GET pages" --> Assets
  UI -- "POST /api/plan" --> API
  API --> RL
  API -- "Structured Outputs" --> OpenAI
  API --> Fallback
  Data --> API

Subsystems#

Subsystem ไฟล์หลัก หน้าเอกสาร
Templates data src/data/templates/*, src/data/*-steps.ts, src/data/template-ids.ts templates-and-composer.md
Composer + placeholders src/lib/composer.ts, src/lib/placeholders.ts, src/lib/types.ts templates-and-composer.md
Script generators + downloads src/lib/scripts.ts, src/lib/download.ts, scripts/export-template.ts scripts-and-share.md
Share encoding src/lib/share.ts scripts-and-share.md
Sanitizer src/lib/sanitize.ts safety-model
AI route + planner + validation src/app/api/plan/route.ts, src/lib/ai/* ai-planner.md
Rate limiting, env, HTTP limits, security headers src/lib/server/*, src/lib/rate-limit.ts, src/lib/security-headers.ts, next.config.ts, public/_headers api-hardening.md
UI framework src/app/tokens.css, src/app/globals.css, src/components/ui/*, src/components/brand/* ui-framework.md
Cloudflare / OpenNext runtime wrangler.jsonc, open-next.config.ts, scripts/patch-opennext.mjs, cloudflare-env.d.ts cloudflare-runtime.md
Chat data model (D1, schema only) migrations/*.sql, binding DB chat-data-model.md

เส้นทาง (routes)#

Route ประเภท หมายเหตุ
/ prerendered หน้าแรก hero + how it works + เทมเพลต + features
/templates prerendered catalog (ค้นหา/กรองฝั่ง client)
/templates/[id] prerendered ต่อ id id ไม่รู้จัก → rewrite ไป /__nvx_not_found เพื่อ HTTP 404 จริง
/builder shell prerendered, builder render ฝั่ง client อ่าน URL hash + localStorage จึงต้องเป็น client-only (builder-loader.tsx)
/design prerendered style guide
GET /api/plan dynamic { serverKeyConfigured, model }
POST /api/plan dynamic สร้าง AgentPlan

ดูเพิ่ม#

data-flow.md, file-map.md, SUBSYSTEM-HISTORY.md

Source: docs/architecture/overview.md · /docs/architecture/overview.md