NekoFlow/README.vi.md

# 🐱 NekoFlow - Monorepo Go + Next.js

[![Ngôn ngữ](https://img.shields.io/badge/Language-English-blue)](README.md) 
[![Ngôn ngữ](https://img.shields.io/badge/Language-Tiếng_Việt-red)](README.vi.md)

> **[Read in English](README.md)**

Template monorepo sẵn có để xây dựng ứng dụng single binary kết hợp Go backend với Next.js frontend. Hoàn hảo cho các developer cần một nền tảng hiện đại, sẵn sàng production thay vì phải build từ đầu.

## 🎯 NekoFlow là gì?

NekoFlow là một **template monorepo được dựng sẵn** dành cho các developer muốn:

- ✅ **Bắt đầu ngay lập tức** thay vì mất thời gian setup boilerplate
- ✅ **Xây dựng ứng dụng single binary** (giống Gitea, nhưng cho web app)
- ✅ **Sử dụng tech stack hiện đại** (Go + Next.js + TypeScript + Tailwind)
- ✅ **Deploy dễ dàng** chỉ với một file executable
- ✅ **Scale nhanh chóng** với nền tảng vững chắc

Phù hợp cho:
- **Internal tools** và admin dashboards
- **Microservices** có giao diện web
- **Desktop applications** với web UI
- **Prototypes** và MVPs
- **Học tập** tích hợp Go + Next.js

## 📦 Cấu Trúc Dự Án

```
nekoflow/
├── apps/
│   ├── web/              # Next.js 14 (Frontend - Static Export)
│   └── server-go/        # Go backend + Static file server
├── scripts/              # Build scripts
└── dist/                 # Build output
```

## 🚀 Bắt Đầu Nhanh

### Yêu Cầu
- Node.js 18+
- Go 1.21+

### Cài Đặt

```bash
# 1. Cài dependencies
npm install

# 2. Tùy chọn A: Dev chỉ Next.js (có hot reload)
npm run dev:web   # http://localhost:3000

# 3. Tùy chọn B: Full stack với Go
npm run build:dev # Build Next.js + sync sang Go
npm run dev:go    # Chạy Go server → http://localhost:8080
```

## 💻 Phát Triển

### Phát Triển Frontend (Next.js)
```bash
npm run dev:web   # Hot reload trên port 3000
```

### Phát Triển Full Stack (Next.js + Go)

**Terminal 1: Build & sync khi sửa code Next.js**
```bash
npm run build:dev
```

**Terminal 2: Chạy Go server**
```bash
npm run dev:go    # http://localhost:8080
```

**Sau khi sửa code Next.js:**
```bash
npm run build:dev # Build lại và sync
# Go server tự động serve files mới (không cần restart)
```

## 🔨 Build

### Development Build (Nhanh)
```bash
npm run build:dev
# → Build Next.js + sync vào folder static của Go
```

### Production Binary
```bash
npm run build
# → Build Next.js + Go binary
# → Output: dist/nekoflow (single binary ~10-30MB)
```

### Các Lệnh Có Sẵn

| Lệnh | Mô Tả |
|------|-------|
| `npm run dev:web` | Dev Next.js riêng (port 3000, hot reload) |
| `npm run dev:go` | Chạy Go server (port 8080) |
| `npm run build:web` | Build Next.js static export |
| `npm run sync:static` | Copy Next.js build → folder static của Go |
| `npm run build:dev` | Build + sync (cho development) |
| `npm run build` | Build production đầy đủ (tạo binary) |

## 🎯 Deploy

### Deploy Đơn Giản
```bash
# Chỉ cần copy và chạy binary
./dist/nekoflow

# Hoặc chỉ định port
PORT=8080 ./dist/nekoflow
```

### Deploy Lên Linux Server
```bash
# 1. Build cho Linux
npm run build

# 2. Upload
scp dist/nekoflow-linux user@server:/opt/nekoflow

# 3. Chạy trên server
ssh user@server
chmod +x /opt/nekoflow
./nekoflow
```

### Docker (Tùy Chọn)
```dockerfile
FROM scratch
COPY dist/nekoflow /nekoflow
ENTRYPOINT ["/nekoflow"]
```

## 🏗️ Kiến Trúc

### Cách Hoạt Động

```
┌─────────────────────────────────────┐
│     Single Binary (nekoflow)        │
│                                     │
│  ┌────────────┐   ┌──────────────┐ │
│  │ Go Server  │   │ Static Files │ │
│  │            │   │ (Next.js)    │ │
│  │ - API      │   │ - HTML       │ │
│  │ - Router   │   │ - CSS        │ │
│  │ - Embedded │   │ - JS         │ │
│  └────────────┘   └──────────────┘ │
└─────────────────────────────────────┘
         ↓
    Single Port (8080)
         ↓
   ┌─────────────┐
   │  Browser    │
   │  - UI       │
   │  - API call │
   └─────────────┘
```

### Tech Stack

**Frontend:**
- Next.js 14 (Static Export)
- React 18
- TypeScript
- Tailwind CSS

**Backend:**
- Go 1.21+
- gorilla/mux (Router)
- embed (Static files)

**Build:**
- npm workspaces
- Bash scripts
- Go build

## ❓ Câu Hỏi Thường Gặp

### Đây có phải SSR (Server-Side Rendering)?
**Không.** Dự án này dùng Next.js **Static Export** (SSG - Static Site Generation).
- Next.js pre-render pages thành HTML tại thời điểm build
- Go chỉ serve static files (HTML/CSS/JS)
- React hydrate trên client-side
- API calls xảy ra client-side qua `fetch()`

### Có thể dùng getServerSideProps?
**Không.** Static Export không hỗ trợ:
- `getServerSideProps()`
- `getServerData()`
- ISR (Incremental Static Regeneration)

Dùng `'use client'` với `useEffect()` và `fetch()` thay thế.

### Tại sao Go + Next.js?
- ✅ **Single binary** - Deploy dễ dàng
- ✅ **Không cần Node.js runtime** trong production
- ✅ **Performance** - Go nhanh và nhẹ
- ✅ **Modern DX** - React + TypeScript + Tailwind
- ✅ **Cross-platform** - Compile cho Linux/Mac/Windows

### Kích thước binary?
Thường **10-30MB** tùy thuộc:
- Kích thước code Go
- Bundle size của Next.js
- Static assets (hình ảnh, fonts)

### Next.js chỉ là tool để code HTML/CSS/JS dễ hơn?
**Đúng!** Với Static Export:
- Next.js giúp code dễ hơn (React, TypeScript, Components)
- Build ra HTML/CSS/JS thuần
- Go chỉ serve files tĩnh
- Giống như bạn tự viết HTML/CSS/JS nhưng với DX tốt hơn

### HTML của Next.js có gọi Go API?
**Có!** Flow hoạt động:
1. User vào http://localhost:8080
2. Go serve index.html (static)
3. Browser load HTML + React JS
4. React code chạy: `fetch('/api/health')`
5. Request về Go API endpoint
6. Go trả JSON response
7. React update UI

## 📝 License

MIT

## 🤝 Đóng Góp

Chào mừng mọi đóng góp! Thoải mái mở issues hoặc PRs.

---

**Built with ❤️ using Go + Next.js + TypeScript**