## haih.site

Dịch vụ dành cho chủ doanh nghiệp. Khách hàng không cần phải trở thành lập trình viên hay thành thạo các công cụ AI: họ chỉ cần giao việc và nhận lại kết quả hoàn chỉnh. AI được sử dụng trong quá trình vận hành kết hợp với sự giám sát của chuyên gia giàu kinh nghiệm.

Dịch vụ khách hàng chuyên phát triển, chỉnh sửa và bảo trì website dài hạn với AI là công nghệ sản xuất cốt lõi.

haih.site

## Mục tiêu

Phát triển và ra mắt **haih.site** làm trang web công khai chính cho triết lý mới của HAIH.

Trang web không chỉ đơn thuần mô tả công nghệ hoặc engine hiện có, mà còn **giải thích trực quan cho người dùng cuối về cách tiếp cận phát triển mới với AI**, đồng thời cung cấp các showcase hoạt động trực tiếp trên trang, trong khi thư viện trường hợp sử dụng trên GitHub vẫn chưa được hoàn thiện.

## Thông điệp chúng tôi muốn truyền tải

Ý tưởng chính:

> **Đừng bắt đầu dự án bằng một engine cồng kềnh. Hãy bắt đầu với kiến trúc tối thiểu giải quyết đúng bài toán hiện tại, và chỉ thêm lớp tiếp theo khi thực sự cần thiết.**

HAIH nên giúp con người và các coding agent phát triển dự án với chi phí thấp: từ vài file tĩnh cho đến một ứng dụng có kiểu dữ liệu đầy đủ (typed application).

Giá trị cốt lõi không nằm ở số lượng tính năng "có sẵn" (out-of-the-box), mà là **chi phí để bổ sung tính năng cần thiết tiếp theo**.

Nếu bài toán chỉ cần HTML/CSS/JS — không cần React, cơ sở dữ liệu, GraphQL hay application server.

Nếu phát sinh nhu cầu lưu trữ dữ liệu — bổ sung persistence (khả năng lưu trữ).

Nếu cần cung cấp dữ liệu cho các client dạng phần mềm — xuất hiện API.

Nếu API cần frontend — tích hợp client có kiểu dữ liệu rõ ràng.

Nếu cần người dùng — bổ sung hệ thống xác thực (auth).

Nếu cần một sản phẩm thương mại hoàn chỉnh — kiến trúc sẽ mở rộng theo hướng đó, nhưng dự án không phải trả chi phí đó từ trước.

## Định vị

Hiện tại, không nên giới thiệu HAIH như một full-stack framework cồng kềnh khác hay một danh mục các mô đun bắt buộc.

Mô hình chính xác hơn là:

**nền tảng tối thiểu + nguyên tắc kiến trúc tương thích + best practices (thực tiễn tốt nhất) + các trường hợp mẫu theo chiều dọc (vertical cases) hoàn chỉnh dành cho phát triển có sự hỗ trợ của AI.**

Về lâu dài, đây có thể giống một **giao thức kiến trúc (architectural protocol)** hơn là một runtime đơn lẻ: các dự án khác nhau sử dụng các phần khác nhau của ngăn xếp công nghệ (stack), nhưng vẫn giữ được tính dễ đoán và rõ ràng đối với coding agent.

Nguyên tắc cốt lõi:

> **Sử dụng kiến trúc tiết kiệm nhất giải quyết trọn vẹn yêu cầu.**

Mỗi phần phụ thuộc (dependency) mới phải được chứng minh là cần thiết bởi tính năng phục vụ người dùng.

## Trang web này dành cho ai

Trước hết là:

- Các lập trình viên tích cực sử dụng Claude Code, Codex, Cursor và các coding agent khác;
- Lập trình viên đơn lẻ (solo developers) và các nhóm nhỏ cần triển khai và thay đổi sản phẩm nhanh chóng;
- Lập trình viên đã mệt mỏi với sự phức tạp dư thừa của các full-stack boilerplate hiện đại;
- Những người muốn có nền tảng tự lưu trữ/mã nguồn mở (self-hosted/open-source) và khả năng tùy chỉnh kiến trúc theo ý mình;
- Tác giả của các giải pháp và trường hợp sử dụng riêng, những người muốn chia sẻ chúng với cộng đồng sau này.

Trang web phải dễ hiểu đối với một người lần đầu nghe về HAIH và không biết lịch sử của `haih-net/agent` hiện tại.

## Lời hứa tiếp thị chính

Không hứa hẹn "chúng tôi đã triển khai mọi thứ".

Thay vào đó, hãy thể hiện:

> **Bắt đầu với gần như con số không. Chỉ thêm kiến trúc khi yêu cầu bắt buộc.**

Và lời hứa thứ hai:

> **Cung cấp cho coding agent các hợp đồng (contracts) rõ ràng, các ví dụ đã được kiểm chứng và ngữ cảnh tối thiểu — và nó sẽ có thể phát triển dự án cùng với các yêu cầu.**

Sau khi tìm hiểu trang web, người dùng phải hiểu được rằng:

1. họ không bị ép phải chấp nhận một ngăn xếp công nghệ khổng lồ từ trước;
2. một dự án đơn giản thực sự có thể giữ được sự đơn giản;
3. khi các yêu cầu tăng lên, đã có sẵn các lộ trình nâng cấp đã được kiểm chứng;
4. các giải pháp được thiết kế sao cho AI agent có thể dễ dàng hiểu, sửa đổi và kiểm tra;
5. các showcase không phải là ảnh chụp màn hình dạng đồ chơi, mà là các mẫu hoạt động thực tế về chuyển đổi kiến trúc;
6. việc triển khai cuối cùng sẽ được người dùng và AI điều chỉnh cho phù hợp với bài toán cụ thể, chứ không bị bắt buộc cài đặt một mô đun đa năng nào.

## Tại sao điều này quan trọng đối với AI

Trang web cần giải thích rõ ràng về **Trải nghiệm của Agent (Agent Experience - AX)**.

Đối với coding agent, những yếu tố sau là quan trọng:

- Ngữ cảnh tối thiểu cần thiết (minimum necessary context);
- Cấu trúc dự án dễ đoán;
- Tính cục bộ của các thay đổi (locality of changes);
- Các phần phụ thuộc rõ ràng;
- Không trùng lặp thủ công các hợp đồng;
- Các điểm kết nối thành phần có kiểu dữ liệu rõ ràng;
- Lỗi compiler/runtime rõ ràng;
- Cách thức kiểm tra kết quả có thể tái tạo;
- Các trường hợp mẫu có sẵn để mang nguyên tắc kiến trúc sang bài toán mới.

Tính an toàn kiểu dữ liệu xuyên suốt (end-to-end typing) trong các ứng dụng phức tạp nên được thể hiện như một vòng lặp phản hồi (feedback loop) cho AI, ví dụ:

```text
Prisma schema
    ↓
Prisma types
    ↓
Pothos
    ↓
GraphQL schema
    ↓
GraphQL Codegen
    ↓
Typed frontend
    ↓
tsc / tests
```

Tuy nhiên, không được tạo ấn tượng rằng toàn bộ ngăn xếp này là bắt buộc đối với mọi dự án.

## Showcase là phần trung tâm của trang web

Trong khi cơ sở dữ liệu showcase/cases trên GitHub chưa được hoàn thiện, **cần triển khai các showcase nền tảng trực tiếp trên haih.site**.

Showcase phải thể hiện không phải là danh sách công nghệ, mà là các trạng thái kiến trúc hợp lý và quá trình chuyển đổi giữa chúng.

Mỗi showcase phải trả lời được các câu hỏi:

- Bài toán đặt ra là gì;
- Tại sao kiến trúc hiện tại là đủ hoặc đã không còn đủ;
- Yêu cầu mới nào đã xuất hiện;
- Chính xác những gì đã được thêm vào;
- Tại sao không thêm nhiều hơn nữa;
- Cấu trúc dự án trông như thế nào;
- Những phần phụ thuộc nào đã xuất hiện;
- Làm thế nào để kiểm tra kết quả;
- AI có thể mang phần nào từ trường hợp này sang dự án khác.

### Showcase 1. Trang web tĩnh

**Bài toán:** Trang web doanh nghiệp / trang giới thiệu / trang tài liệu không có dữ liệu động.

Kiến trúc tối thiểu:

```text
HTML / CSS / JS / assets
+ Docker Compose
+ Traefik
```

Không có CSDL, GraphQL, xác thực (auth), React hay application server.

Luận điểm chính: **nếu chỉ cần trang tĩnh — không cần engine.**

Cho thấy AI có thể thay đổi một dự án như vậy với chi phí rẻ thế nào.

### Showcase 2. API độc lập

**Bài toán:** Dịch vụ cung cấp API lập trình và hoàn toàn không cần frontend riêng.

Trình bày dự án API-first như một trạng thái hoàn chỉnh độc lập, chứ không phải một trang web chưa hoàn thiện.

Các hướng phát triển:

```text
API only
```

hoặc khi cần persistence:

```text
PostgreSQL
+ Prisma
+ API
```

Cho thấy UI không phải là lớp bắt buộc của hệ thống.

### Showcase 3. Trang web tĩnh + tính năng động nhỏ

**Bài toán:** Ví dụ, biểu mẫu liên hệ (feedback form).

Không vì thế mà biến toàn bộ trang web thành một ứng dụng full-stack.

Hiển thị bước chuyển đổi tối thiểu:

```text
static site
+ small endpoint/service
```

Nếu có thể gửi trực tiếp tin nhắn đến dịch vụ ngoài — không cần thêm CSDL.

Đây là trường hợp quan trọng chống lại việc thiết kế quá đà (overengineering).

### Showcase 4. Trang web có persistence (lưu trữ)

**Bài toán:** Dữ liệu cần phải được lưu trữ: đơn hàng, danh mục, bản ghi hoặc đối tượng miền (domain object) khác.

Bổ sung:

```text
PostgreSQL
+ Prisma
```

Giới thiệu Prisma như nguồn cung cấp mô hình dữ liệu có kiểu rõ ràng và giải thích lý do tại sao persistence xuất hiện ở giai đoạn này.

API và frontend phức tạp chỉ được thêm vào nếu bài toán thực sự yêu cầu.

### Showcase 5. API có kiểu dữ liệu rõ ràng dựa trên dữ liệu

**Bài toán:** Dữ liệu đã lưu cần được sử dụng bởi nhiều client hoặc frontend cần làm việc với một API đầy đủ.

Thêm ví dụ:

```text
PostgreSQL
+ Prisma
+ Pothos
+ GraphQL
```

Hiển thị mối liên hệ giữa các kiểu của Prisma và GraphQL, đồng thời giảm thiểu mã nối (glue code) thủ công.

### Showcase 6. Ứng dụng web hoàn chỉnh có kiểu dữ liệu rõ ràng

**Bài toán:** Xuất hiện frontend tương tác làm việc với API riêng.

Kiến trúc phát triển thành:

```text
PostgreSQL
+ Prisma
+ Pothos / GraphQL
+ GraphQL Codegen
+ client
+ UI
```

Hiển thị hợp đồng xuyên suốt **database → server → API → frontend** và việc kiểm tra thay đổi tự động bằng trình biên dịch (compiler).

Không định vị framework frontend là bắt buộc. Việc chọn React hay giải pháp khác phải xuất phát từ bài toán cụ thể.

### Showcase 7. Ứng dụng người dùng có xác thực

**Bài toán:** Xuất hiện dữ liệu cá nhân, tài khoản hoặc các thao tác bị giới hạn quyền.

Chỉ đến lúc này mới thêm auth/session/permissions.

Chứng minh rằng xác thực không phải là cơ sở hạ tầng bắt buộc của mọi trang web, mà là câu trả lời cho một yêu cầu cụ thể.

Minh họa cách truyền thông tin định danh/quyền hạn qua API và UI mà không làm phá vỡ kiến trúc trước đó.

### Showcase 8. Cửa hàng trực tuyến hoàn chỉnh

**Bài toán:** Sản phẩm thực tế phức tạp.

Cần xuất hiện các phần miền cần thiết, ví dụ:

- Danh mục sản phẩm;
- Phân loại;
- Trang chi tiết sản phẩm;
- Tìm kiếm/lọc (nếu yêu cầu đặt ra);
- Giỏ hàng;
- Người dùng/người mua hàng;
- Quy trình thanh toán;
- Đơn hàng và trạng thái đơn hàng;
- Quản lý sản phẩm và đơn hàng phía quản trị viên;
- Hình ảnh/tệp tin;
- Tích hợp thanh toán như một bước kiến trúc độc lập;
- Các tiến trình nền/thông báo cần thiết.

Showcase này phải chứng minh rằng cách tiếp cận tối giản không chỉ giới hạn ở các trang landing: **từ cùng một hệ thống nguyên tắc, ta có thể tiến hóa thành một ứng dụng hướng sản xuất (production-oriented) hoàn chỉnh.**

Đồng thời, cần thể hiện trực quan/kiến trúc nguồn gốc của độ phức tạp: mỗi lớp mới tồn tại vì một yêu cầu kinh doanh cụ thể đòi hỏi nó.

## Thể hiện cả trạng thái lẫn quá trình chuyển đổi

Nên liên kết các showcase thành một đồ thị trực quan thay vì một chiếc thang tuyến tính.

Ví dụ:

```text
                  ┌→ small endpoint
static website ───┤
                  └→ persistence → API → typed web app → auth → commerce

API service ─────────→ persistence
        └────────────→ agent/client integrations
```

Ý tưởng chính: **không có ngăn xếp đích bắt buộc.**

Người dùng có thể dừng lại ở bất kỳ điểm nào nếu nó giải quyết trọn vẹn bài toán.

## Mỗi showcase trên trang web cần làm những gì

Không giới hạn ở việc mô tả bằng văn bản.

Nếu có thể, mỗi showcase phải là một ví dụ hoạt động thực tế:

- Mở xem kết quả;
- Xem kiến trúc/cấu trúc;
- Nhìn thấy các thành phần được sử dụng;
- Xem diff hoặc chuỗi thay đổi so với trạng thái trước đó;
- Đọc giải thích ngắn gọn về quyết định kiến trúc;
- Xem cách thức kiểm tra;
- Nhận hướng dẫn/prompt/ngữ cảnh để coding agent có thể tái tạo hoặc điều chỉnh giải pháp.

Về sau, các tài liệu này có thể được chuyển ra/đồng bộ hóa với các trường hợp mẫu riêng trên GitHub.

## Cấu trúc đề xuất cho trang chủ

### Hero

Giải thích cực kỳ ngắn gọn điểm khác biệt của HAIH.

Không phải "một AI framework khác", mà là ý tưởng về kiến trúc tiến hóa tối thiểu để phát triển cùng với các coding agent.

CTA chính nên dẫn đến các showcase đang hoạt động.

### Vấn đề

Các boilerplate/framework hiện đại thường ép dự án phải trả trước chi phí cho độ phức tạp.

AI phải trả thêm chi phí cho độ phức tạp đó bằng ngữ cảnh và số lượng mối liên hệ mà nó phải hiểu.

### Nguyên tắc

**Bắt đầu tối thiểu. Chỉ thêm những gì yêu cầu tiếp theo cần đến.**

Hiển thị sự tiến hóa trực quan từ trang tĩnh đến ứng dụng phức tạp.

### Live showcase

Phần trung tâm của trang web với các trường hợp mẫu đã mô tả ở trên.

### AI / AX

Giải thích lý do tại sao kiến trúc được tối ưu hóa đặc biệt cho coding agent: context, locality, types, compiler feedback, tests, cases.

### Best practices / Cases

Giải thích mô hình cơ sở tri thức: không áp đặt một cách triển khai cuối cùng duy nhất, mà tập hợp các giải pháp kiến trúc đã được kiểm chứng và các thay đổi theo chiều dọc hoàn chỉnh.

### Open source / Tham gia

Giải thích vòng lặp cộng đồng trong tương lai:

```text
requirement
→ minimal solution
→ verified case
→ AI reuse
→ new projects
→ new cases
```

Mời gọi dùng thử phương pháp, điều chỉnh các trường hợp mẫu và xuất bản giải pháp của riêng mình.

## Những điều không nên hứa hẹn lúc này

- Không định vị HAIH là một nền tảng SaaS đa năng có sẵn;
- Không nhấn mạnh vào việc bán hàng/kiếm tiền;
- Không hứa hẹn một chợ ứng dụng (marketplace) khổng lồ chứa các mô đun có sẵn mà thực tế chưa có;
- Không tạo ấn tượng rằng Prisma/Pothos/Apollo/React là bắt buộc;
- Không mang toàn bộ danh sách tính năng của `haih-net/agent` cũ sang sản phẩm mới;
- Không nói rằng chỉ có duy nhất một kiến trúc đúng;
- Không làm quá tải trang chủ bằng các chi tiết kỹ thuật trước khi người dùng hiểu được giá trị.

## Tiêu chí thành công của trang web

Một khách truy cập mới không biết lịch sử của HAIH, sau khi xem trang web phải hiểu được rằng:

> "Tôi có thể bắt đầu với một dự án tối thiểu. Khi có yêu cầu mới, AI có thể lấy trường hợp mẫu đã được kiểm chứng, chỉ thêm kiến trúc cần thiết và kiểm tra kết quả. Tôi không cần phải chấp nhận một framework khổng lồ từ trước và mang vào dự án những tính năng mà tôi chưa dùng đến."

Sau khi hiểu được ý tưởng này, người dùng phải có khả năng **mở ngay một live showcase**, nhìn thấy nó trên một dự án thực tế và nhận đủ thông tin để tự mình thử nghiệm cách tiếp cận tương tự.

## Mục tiêu phổ biến

Ở giai đoạn hiện tại, tối ưu hóa trang web để **hiểu ý tưởng, thử nghiệm và tham gia**, chứ không phải để bán hàng.

Chu kỳ mong muốn:

```text
khách truy cập
→ hiểu nguyên tắc
→ xem live case
→ thử nghiệm cách tiếp cận
→ điều chỉnh giải pháp cùng AI
→ chia sẻ case/best practice của riêng mình
→ người dùng tiếp theo có thêm một con đường đã được kiểm chứng
```

Trang web phải trở thành màn trình diễn công khai đầu tiên của mô hình này và tạm thời đóng vai trò là cửa sổ trưng bày/cơ sở dữ liệu các showcase cốt lõi cho đến khi danh mục trường hợp mẫu mở hoàn chỉnh ra đời.

Phát triển và ra mắt haih.site làm trang web sản phẩm cho triết lý mới của HAIH: kiến trúc tối thiểu phát triển cùng các yêu cầu, cùng các bản showcase trực quan từ trang web tĩnh, API độc lập cho đến một cửa hàng trực tuyến hoàn chỉnh.

Phát triển và ra mắt trang web

## Mục tiêu

Bổ sung hệ thống quan sát (observability) trọng lượng nhẹ cho trang web, giúp nhanh chóng nắm bắt:

- trang web và các dịch vụ cốt lõi có đang hoạt động không;
- lỗi phát sinh ở đâu;
- hiệu suất thay đổi như thế nào;
- có sự suy giảm về thời gian phản hồi, tải hoặc tài nguyên hay không.

## Hạn chế và ưu tiên

- **Không sử dụng Sentry** làm công cụ chính.
- Tránh hạ tầng cồng kềnh và dư thừa.
- Ưu tiên các giải pháp đơn giản, dễ hiểu và chi phí thấp / tự lưu trữ (self-hosted).
- Xem xét stack ở mức **nhật ký có cấu trúc + Prometheus + Grafana** và các giải pháp thay thế nhẹ hơn nếu chúng giải quyết bài toán đơn giản hơn.

## Những việc cần nghiên cứu

1. Xác định tập hợp quan sát tối thiểu cho kiến trúc trang web hiện tại.
2. Cấu hình việc thu tập nhật ký tập trung và giao diện xem thuận tiện cho ứng dụng/máy chủ web.
3. Thêm các số liệu ít nhất về:
   - tính khả dụng;
   - trạng thái HTTP / tỷ lệ lỗi;
   - độ trễ / thời gian phản hồi;
   - tần suất yêu cầu (request rate);
   - CPU, RAM, ổ đĩa và các tài nguyên quan trọng khác của máy chủ/container, nếu có.
4. Thêm các số liệu ứng dụng cho các thao tác quan trọng của trang web khi cần thiết.
5. Xây dựng bảng điều khiển gọn nhẹ về trạng thái và hiệu suất.
6. Thêm các cảnh báo cơ bản cho các trạng thái sự cố rõ ràng và tình trạng suy giảm đáng kể.
7. Kiểm tra ảnh hưởng của chính hệ thống giám sát đối với tài nguyên và tránh làm cho việc vận hành trở nên phức tạp một cách bất hợp lý.

## Các ứng viên

Phương án cơ bản để đánh giá:

- nhật ký ứng dụng / máy chủ web có cấu trúc;
- Prometheus;
- exporters / ứng dụng có endpoint `/metrics`;
- Grafana;
- backend nhẹ cho nhật ký nếu cần thiết (ví dụ Loki hoặc tương tự), miễn là có căn cứ hợp lý.

Cho phép chọn stack đơn giản hơn nếu nó đảm bảo khả năng chẩn đoán đầy đủ và chi phí vận hành thấp hơn.

## Kết quả

- đã chọn và đưa ra lý do cho stack giám sát tối thiểu;
- hệ thống giám sát đã được triển khai và kết nối với trang web;
- có sẵn nhật ký và các số liệu cơ bản;
- có bảng điều khiển với các chỉ số chính;
- đã cấu hình các cảnh báo tối thiểu cần thiết;
- có tài liệu hướng dẫn nơi xem trạng thái hệ thống và cách chẩn đoán các sự cố thông thường.

Lựa chọn và triển khai hệ thống theo dõi trang web nhẹ không dùng Sentry: nhật ký (logs), số liệu (metrics), bảng điều khiển (dashboards) và cảnh báo cơ bản.

Nhiệm vụ

Nghiên cứu và bổ sung tính năng theo dõi hoạt động và hiệu suất của trang web

Phát triển và ra mắt trang web