# Tổng Quan Công Nghệ & Kiến Trúc Dự Án (Project Tech Overview & Template)

> **Mục đích**: Tài liệu này tổng hợp kiến trúc công nghệ chung của dự án web/tool hiện tại. Cấu trúc được thiết kế tinh gọn, chuẩn hóa để có thể sao chép và tái sử dụng nhanh chóng cho các dự án web app/editor/game tool tương tự trong tương lai.

---

## 1. Tổng Quan Kiến Trúc (Architecture Overview)

* **Loại ứng dụng**: Web Application / Editor Tool (Single Page Application - SPA).
* **Mô hình hoạt động**: Client-side Rendering (CSR) hoàn toàn trên trình duyệt, không phụ thuộc nặng vào backend.
* **Nguyên tắc thiết kế**:
  * **Zero-Framework Overhead**: Sử dụng Vanilla JavaScript kết hợp ES Modules để tối ưu hiệu năng, giảm dung lượng bundle và đơn giản hóa việc bảo trì.
  * **Modular Component Architecture**: Chia nhỏ các thành phần xử lý (UI, Logic Game, Analytics, Data Management, Audio, IO/Export) thành các file JS độc lập.
  * **Fast Feedback Loop**: Sử dụng Vite làm Build Tool giúp khởi động dev server tức thì (HMR).

---

## 2. Công Nghệ Cốt Lõi (Core Tech Stack)

| Hạng mục | Công nghệ / Thư viện | Vai trò & Mục đích |
| :--- | :--- | :--- |
| **Language** | JavaScript (ES6+) | Ngôn ngữ lập trình chính, sử dụng ES Modules (`import/export`) |
| **Markup & Styling** | HTML5, Vanilla CSS3 | Dựng cấu trúc giao diện và tạo style/giao diện người dùng |
| **Build Tool** | [Vite](https://vitejs.dev/) | Hỗ trợ Local Dev Server, HMR và đóng gói production bundle |
| **Data Compression** | [JSZip](https://stuk.github.io/jszip/) | Nén/giải nén file dữ liệu, level pack, assets dưới dạng file ZIP |
| **Package Manager** | npm | Quản lý phụ thuộc dự án |

---

## 3. Cấu Trúc Thư Mục Chuẩn (Standard Directory Structure)

```text
├── css/                  # File kiểu dáng UI/UX (Stylesheets)
├── docs/                 # Tài liệu kỹ thuật, hướng dẫn & workflow
├── js/                   # Mã nguồn JavaScript chính (Modules)
│   ├── game/             # Logic xử lý lõi (Core Engine / Game Loop)
│   ├── utils/            # Thư viện tiện ích dùng chung (Helper functions)
│   ├── main.js           # Entry point của ứng dụng
│   ├── game.js           # Điều phối trạng thái game/editor
│   ├── editor_ui.js      # Quản lý giao diện người dùng (UI Controllers)
│   ├── levels.js         # Quản lý dữ liệu màn chơi / level data
│   └── audio.js          # Hệ thống âm thanh (Audio Manager)
├── public/               # Tài nguyên tĩnh (Images, Audio, Fonts, Icons)
├── index.html            # Trang HTML chính của SPA
├── package.json          # Cấu hình dự án và dependencies
└── vite.config.js        # Cấu hình Vite Build Tool
```

---

## 4. Quy Trình Vận Hành & Phát Triển (Workflow & Commands)

### 4.1. Khởi tạo môi trường (Setup)
```bash
npm install
```

### 4.2. Chạy môi trường phát triển (Development)
```bash
npm run dev
```

### 4.3. Đóng gói ứng dụng (Production Build)
```bash
npm run build
```

### 4.4. Kiểm tra bản build (Preview)
```bash
npm run preview
```

---

## 5. Hướng Dẫn Tái Sử Dụng Cho Dự Án Mới (Quick Reusability Guide)

Khi bắt đầu một dự án mới dựa trên framework/cấu trúc này:

1. **Khởi tạo dự án nhanh**:
   ```bash
   npx -y create-vite@latest my-new-project --template vanilla
   cd my-new-project
   npm install jszip
   ```
2. **Sao chép cấu trúc thư mục chuẩn**:
   * Tạo thư mục `js/`, `css/`, `docs/`, `public/`.
   * Cấu hình `vite.config.js` cơ bản.
3. **Triển khai các Mô-đun lõi**:
   * **State & Data Management**: Tạo module điều phối dữ liệu (tương tự `levels.js`).
   * **UI Handler**: Tách riêng xử lý DOM và Event Listeners khỏi Core Logic.
   * **Export/Import**: Dùng `JSZip` hoặc `Blob` Web APIs để xuất/nhập dữ liệu file `.json`/`.zip`.