Resume Web + GitHub Cache

เว็บพอร์ตโฟลิโอที่เชื่อมต่อ GitHub แบบเรียลไทม์ พร้อม Express backend สำหรับ cache, Gemini 2.5 Flash เพื่อสรุป “focus areas” และบริการ music search ผ่าน Lavalink สำหรับเพลงพื้นหลัง

🎯 Highlights

• 🔄 Smart GitHub cache: file-based cache 2 นาที + stale fallback, refresh อัตโนมัติ และ SSE /events ส่งอัปเดตถึง frontend
• 🤖 Gemini focus areas: สร้าง 4 focus cards จาก repo/ภาษา/หัวข้อ GitHub พร้อมตรวจ hash กัน regenerate เกินจำเป็น
• 📊 Repo insights: endpoints สำหรับ repos, README HTML, language stats, tech stack และการดึงภาษาแบบ batch
• 🎛️ Background music API: proxy หาเพลงผ่าน Lavalink (/music/*) เพื่อใช้เล่น ambient music ในหน้าเว็บ
• 🖥️ React + Vite: หน้า Home/Work ดึงข้อมูลจาก backend, cache ฝั่ง client, modal รายละเอียด repo, animations (framer-motion)

📁 Project Structure

Express/   # Backend cache + Gemini + Lavalink proxy
React/     # Frontend (Vite) สำหรับ resume/work showcase

🚀 Getting Started

Prerequisites

• Node.js 18+ และ npm
• (แนะนำ) GitHub token สำหรับ rate limit สูงขึ้น
• (ตัวเลือก) Gemini API key สำหรับ focus areas
• (ตัวเลือก) Lavalink node + Java 17 หากใช้ music endpoints

1) Backend (Express)

cd Express
npm install

สร้างไฟล์ .env (ตัวอย่าง):

PORT=3001
GITHUB_TOKEN=your_github_token
GEMINI_API_KEY=your_gemini_key          # เว้นว่างได้ จะใช้ fallback focus areas
LAVALINK_HOST=localhost                 # สำหรับ /music/*
LAVALINK_PORT=2333
LAVALINK_PASS=youshallnotpass
MUSIC_SOURCE=ytsearch                   # ค่าเริ่มต้นสำหรับ search

รันเซิร์ฟเวอร์:

npm start

เซิร์ฟเวอร์จะสร้างโฟลเดอร์ Express/.cache ให้อัตโนมัติ และเริ่ม background refresh ทุก 2 นาที

2) Frontend (React)

cd React
npm install

ไฟล์ .env (ไม่บังคับ):

VITE_API_URL=http://localhost:3001
VITE_GITHUB_TOKEN=your_github_token     # สำหรับเรียก backend ต่อ GitHub ได้สูงขึ้น

รัน dev server:

npm run dev

เปิดที่ http://localhost:5173

🔌 Key API Endpoints (backend)

• GET /api/repos/:username — รายชื่อ repo (cache 2 นาที)
• GET /api/repos/:username/:repo/readme — README (HTML) พร้อม cache
• GET /api/stats/languages/:username?refresh=true|false — language stats รวม
• GET /api/tech-stack/:username?refresh=true|false — top tech/languages/topics
• GET /api/focus-tracks/:username?refresh=true|false — 4 focus areas จาก Gemini + repo hash guard
• POST /api/cache/clear — ล้างไฟล์ cache ทั้งหมด
• GET /health — สถานะเซิร์ฟเวอร์และจำนวนไฟล์ cache
• GET /events — SSE สำหรับแจ้ง cache update ไปยัง frontend

Music (Lavalink) endpoints

• GET /music/search?q=...&source=ytsearch|scsearch — ค้นหาเพลง/เพลย์ลิสต์
• GET /music/track?url= — ดึง track จาก URL เดี่ยว
• GET /music/decode?track= — ถอดรหัส track ที่ encode
• GET /music/node/info และ /music/node/stats — สถานะ Lavalink
• GET /music/stream?encoded= — URL สำหรับใช้งานกับ Lavalink player
• GET /music/background?q= — เพลย์ลิสต์ ambient (สุ่ม keyword ถ้าไม่ส่ง q)

🧠 Data & Cache Flow (สรุป)

1. Frontend เรียก /api/repos, /api/stats/languages, /api/focus-tracks → backend cache 2 นาที + stale fallback ถ้า GitHub ล่ม
2. เมื่อ repo hash เปลี่ยน จะ regenerate focus areas; ไม่เปลี่ยนจะใช้ cache เดิม
3. Background job รีเฟรช cache ของผู้ใช้ที่เคยถูกเรียก และ broadcast ผ่าน SSE
4. Frontend ใช้ local cache (utils/cache.js) + SSE event cache-updated เพื่ออัปเดตหน้าทันทีโดยไม่รีเฟรช

🧠 Smart Cache (backend + frontend)

• Backend: file cache TTL 2 นาทีใน Express/.cache + stale fallback ถ้า GitHub error, background refresh ทุก 2 นาที (ผู้ใช้ที่ถูกเรียกแล้ว) และส่ง SSE /events เมื่อ data เปลี่ยน
• Focus areas: ผูกกับ repo hash (.username.hash.json) ถ้า hash เดิมจะไม่ regenerate Gemini; force refresh ด้วย ?refresh=true
• Repo/lang/tech: cache แยกไฟล์ (repos_*, lang_stats_*, tech_stack_*) พร้อม force refresh query
• Frontend: client cache (utils/cache.js) เก็บ repos/focus areas ชั่วคราว + ฟัง SSE เพื่อ sync อัตโนมัติ; ถ้าเปิดหน้าใหม่จะใช้ cache ก่อนลด loading time
• Error-handling: ถ้า GitHub API ล่มหรือช้า → backend ส่ง stale cache + flag stale:true ช่วย frontend แสดงผลต่อเนื่อง

🖼️ Frontend Screens

• Home: hero + contact, GitHub stack, dynamic focus cards (Gemini), CTA ไป CV/Email, ลิงก์ไปหน้า work
• Work: language stats chart, repo grid (รวม README snippet), modal รายละเอียด repo พร้อม forks/stars
• BackgroundMusic component เรียก /music/background เพื่อสุ่มเพลงเปิดฟัง

🧪 Quick Checks

• npm start (Express) แล้วดู log: Gemini ready?, GitHub token?, SSE ready
• npm run dev (React) แล้วทดสอบ: focus cards โหลดไหม, repos แสดงไหม, stats chart มีข้อมูลหรือไม่

📝 Notes

• ถ้าไม่มี Gemini key จะได้ focus areas แบบ fallback
• GitHub Api rate limit: 60 req/hr ถ้าไม่มี token, 5000 req/hr ถ้ามี token

---

Last Updated: December 5, 2025