FutureX

FutureX là nền tảng lập trình giáo dục dựa trên Scratch 3.0, được tùy chỉnh và phát triển để mang lại trải nghiệm học lập trình trực quan, sáng tạo cho học sinh.

✨ Tính năng

• Giao diện lập trình kéo-thả trực quan dựa trên Scratch 3.0
• Hỗ trợ các dự án multimedia: hình ảnh, âm thanh, animation
• Tích hợp chatbot AI (futureX BOT) — hỏi đáp thông minh dựa trên tài liệu
• Hỗ trợ kết nối thiết bị vật lý (micro:bit)
• Đa ngôn ngữ (tiếng Việt và các ngôn ngữ khác)
• Deploy sẵn sàng lên Vercel

🛠️ Yêu cầu hệ thống

• Node.js (khuyến nghị v18 trở lên)
• Git
• npm (đi kèm với Node.js)

🚀 Cài đặt & Chạy local

1. Clone repository

git clone https://github.com/do-hu-so/FutureX.git
cd FutureX

2. Cài đặt dependencies

npm install

3. Cấu hình API Keys

Tạo file .env từ template:

copy .env.example .env

Điền các giá trị vào .env:

GROQ_API_KEY=your_groq_api_key        # lấy tại console.groq.com
PINECONE_API_KEY=your_pinecone_key    # lấy tại app.pinecone.io
PINECONE_INDEX=scratch-academy

Lưu ý: File .env đã được thêm vào .gitignore, không bao giờ commit file này lên GitHub.

4. Chạy môi trường phát triển

# Chạy đồng thời webpack dev server + API server
npm run dev

# Hoặc chạy riêng từng phần:
npm run start    # webpack dev server tại http://localhost:8601
npm run server   # API server tại http://localhost:3000

🤖 Thêm dữ liệu cho futureX BOT

Bot sử dụng Pinecone vector database để lưu và tra cứu kiến thức. Để thêm tài liệu cho bot học:

Bước 1 — Đặt file vào thư mục /data

FutureX/
└── data/
    ├── tai-lieu-khoa-hoc.docx
    ├── huong-dan-su-dung.pdf
    └── faq.txt

Định dạng hỗ trợ: .docx, .pdf, .txt

Bước 2 — Chạy lệnh ingest

npm run ingest

Script sẽ tự động:

1. Đọc tất cả file trong thư mục /data
2. Chia nội dung thành các đoạn nhỏ (chunks)
3. Tạo vector embedding cho từng đoạn
4. Upload lên Pinecone index scratch-academy

Sau khi ingest xong, bot sẽ có thể trả lời câu hỏi dựa trên nội dung các file đó.

🏗️ Build cho production

npm run build

Kết quả build sẽ nằm trong thư mục ./build/.

☁️ Deploy lên Vercel

Deploy tự động (khuyến nghị)

1. Push code lên GitHub
2. Import repository tại vercel.com
3. Vào Settings → Environment Variables, thêm 3 biến:

Tên biến	Giá trị
GROQ_API_KEY	API key từ console.groq.com
PINECONE_API_KEY	API key từ app.pinecone.io
PINECONE_INDEX	scratch-academy

4. Nhấn Redeploy — chatbot sẽ hoạt động ngay sau đó.

Deploy thủ công qua Vercel CLI

npm install -g vercel
vercel

Lưu ý: Build output được cấu hình tại thư mục build/ trong file vercel.json.

📁 Cấu trúc project

FutureX/
├── api/                    # Vercel Serverless Functions (AI backend)
│   ├── chat.ts             # POST /api/chat — hỏi đáp AI
│   └── lib/
│       ├── groq.ts         # Groq LLM client
│       └── pinecone.ts     # Pinecone vector DB client
├── data/                   # Tài liệu để ingest vào Pinecone
├── scripts/
│   ├── server.ts           # Local dev API server
│   └── ingest-data.ts      # CLI ingest data vào Pinecone
├── src/                    # Source code frontend (Scratch GUI)
│   ├── components/
│   │   └── chatbot/        # futureX BOT component
│   ├── containers/
│   ├── reducers/
│   └── lib/
├── static/                 # Assets tĩnh
├── .env.example            # Template API keys
├── vercel.json             # Cấu hình deploy Vercel
├── webpack.config.js       # Cấu hình Webpack
└── package.json            # Dependencies & scripts

📜 Scripts

Lệnh	Mô tả
npm run dev	Chạy webpack + API server cùng lúc
npm run start	Chỉ chạy webpack dev server (port 8601)
npm run server	Chỉ chạy API server (port 3000)
npm run ingest	Ingest dữ liệu từ /data vào Pinecone
npm run build	Build production vào thư mục build/
npm test	Chạy toàn bộ test suite
npm run test:unit	Chạy unit tests
npm run test:lint	Kiểm tra code style

🧪 Kiểm thử

npm run test:unit
npm run test:lint

📄 License

Dự án này được phân phối dưới giấy phép AGPL-3.0.

---

FutureX được xây dựng dựa trên scratch-gui của Scratch Foundation.