build-app-with-ai

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

build-app-with-ai

★ 13 Open GitHub ↗

Build App With AI là một monorepo được xây dựng để PO, BA, Dev và QA có thể cùng sử dụng AI trong một quy trình làm việc thống nhất. Dự án gom tài liệu, prototype, ứng dụng và automation test vào cùng một nơi để giúp team đi xuyên suốt từ yêu cầu đến triển khai.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Build App With AI

Monorepo này được tổ chức để hỗ trợ một quy trình làm sản phẩm end-to-end trong cùng một repo:

- PO, BA, Dev, QA cùng làm việc trên một nguồn sự thật chung.
- Spec, prototype, app web và test automation được giữ gần nhau.
- Từ một feature có thể truy vết theo chuỗi: `spec -> UI/prototype -> implementation -> test`.

Repo dùng:

- `pnpm` workspace
- `Turborepo`
- `Next.js`
- `shadcn/ui`
- `Quartz` cho tài liệu
- `Playwright` cho E2E test

## Mục Tiêu

Thay vì tách tài liệu, prototype, source code và test case ra nhiều nơi khác nhau, repo này gom tất cả vào một monorepo để:

- giảm độ lệch giữa spec và implementation
- giúp stakeholder review được luồng UI sớm
- giúp QA bám đúng acceptance criteria
- giúp Dev tái sử dụng UI component và test selector
- giúp team mở rộng feature theo cùng một cách làm

## Cấu Trúc Repo

```text
build-app-with-ai/
├── apps/
│   ├── docs/          # Tài liệu Quartz: spec, test case, kiến thức dự án
│   ├── playground/    # Nơi thử nghiệm luồng UI/UX, rehearsal automation
│   └── web/           # Ứng dụng web chính
├── packages/
│   ├── eslint-config/ # Shared ESLint config
│   ├── typescript-config/
│   └── ui/            # Shared UI package dùng cho web/playground
├── tests/
│   └── e2e/           # Playwright tests
├── package.json
├── pnpm-workspace.yaml
└── turbo.json
```

## Vai Trò Từng App

### `apps/docs`

Đây là trung tâm tài liệu của dự án, dùng Quartz để lưu:

- feature spec
- acceptance criteria
- test case
- flow nghiệp vụ
- tài liệu handoff giữa PO, BA, Dev, QA

Nên coi `apps/docs` là nơi ghi lại quyết định và kỳ vọng nghiệp vụ.

### Vì Sao Dùng Quartz

Repo này không dùng Quartz chỉ để “render Markdown”, mà dùng nó như một lớp tài liệu sống cho toàn bộ quy trình làm sản phẩm.

Lý do chọn Quartz:

- tài liệu được viết bằng Markdown nên PO, BA, Dev, QA đều dễ tham gia
- dễ tạo liên kết chéo giữa spec, test case, flow, quyết định nghiệp vụ và ghi chú kỹ thuật
- phù hợp với mô hình knowledge hub trong cùng monorepo
- tài liệu nằm gần source code nên giảm lệch ngữ cảnh giữa “tài liệu nói gì” và “code đang làm gì”
- dễ review thay đổi bằng Git thay vì chỉnh sửa trên một hệ thống tài liệu tách rời
- thuận tiện cho việc trace một feature từ yêu cầu đến implementation và test

Trong repo này, Quartz đặc biệt phù hợp vì team đang cần:

- một nơi lưu spec
- một nơi lưu test case
- một nơi lưu flow review/handoff
- khả năng liên kết các phần đó với `playground`, `web` và `tests/e2e`

Nói ngắn gọn: Quartz được dùng vì nó biến tài liệu thành một phần của hệ thống phát triển, không phải một phần tách biệt.

### `apps/playground`

Đây là môi trường thử nghiệm UI/UX và interaction trước khi đưa vào app chính.

Nên dùng `playground` khi cần:

- demo luồng cho stakeholder
- validate bố cục hoặc interaction
- thử selector cho automation
- rà happy path trước khi nối backend thật

`playground` không nên trở thành “app production thứ hai”.

### `apps/web`

Đây là ứng dụng web chính, đại diện cho hướng triển khai thật.

Khi feature đủ rõ từ spec và playground, phần implementation nên đi vào `web`.

### `packages/ui`

Đây là nơi chứa design system và shared component dùng chung giữa `web` và `playground`.

Ví dụ:

- `Button`
- `Card`
- `Input`
- `Label`
- utility như `cn`
- shared `globals.css`

## Quy Trình Làm Việc Đề Xuất

Một flow feature trong repo này nên đi theo thứ tự:

1. Viết spec trong `apps/docs`
2. Xác định acceptance criteria và test case
3. Dựng UI flow trong `apps/playground`
4. Chuyển sang implementation trong `apps/web`
5. Gắn `data-testid` ổn định cho UI
6. Viết hoặc cập nhật Playwright test trong `tests/e2e`
7. Review lại tính khớp giữa spec, UI, code và test

Điểm quan trọng là mọi phần đều nên bám vào cùng một flow nghiệp vụ, không tách rời nhau.

## Yêu Cầu Môi Trường

Khuyến nghị dùng:

- `Node.js >= 22`
- `pnpm 9`

Lý do:

- repo đã được chuẩn hóa để dùng Node 22 làm baseline thống nhất
- `apps/docs` dùng Quartz và yêu cầu Node 22
- dùng cùng một version Node ở root giúp giảm lỗi lệch môi trường giữa các app

Kiểm tra nhanh:

```bash
node -v
pnpm -v
```

## Cài Đặt

Chạy tại root repo:

```bash
cd /Users/test/Develop/build-app-with-ai
pnpm install
```

Nếu dùng Playwright lần đầu, cài browser:

```bash
pnpm run e2e:install
```

## Lệnh Theo Từng Phần

### Root Workspace

Chạy từ root repo:

```bash
pnpm run dev
pnpm run build
pnpm run lint
pnpm run format
pnpm run typecheck
```

Ý nghĩa:

- `dev`: chạy các app đang có task `dev` trong Turborepo
- `build`: build toàn bộ workspace theo dependency graph
- `lint`: lint toàn workspace
- `format`: format toàn workspace theo script của từng package/app
- `typecheck`: kiểm tra TypeScript toàn workspace

Nếu chỉ cần nhớ một nhóm lệnh cơ bản, đây là các lệnh root dùng thường xuyên nhất:

```bash
pnpm run dev
pnpm run build
pnpm run lint
pnpm run format
pnpm run typecheck
```

### `apps/web`

Chạy riêng ứng dụng web chính:

```bash
pnpm run web:dev
pnpm --filter web build
pnpm --filter web lint
pnpm --filter web format
pnpm --filter web typecheck
```

Khi dùng:

- dùng `web:dev` khi muốn review app chính
- dùng `build` khi kiểm tra khả năng production build
- dùng `typecheck` khi vừa thay đổi component hoặc route

### `apps/playground`

Chạy riêng playground:

```bash
pnpm run playground:dev
pnpm --filter playground build
pnpm --filter playground lint
pnpm --filter playground format
pnpm --filter playground typecheck
```

Khi dùng:

- dùng `playground:dev` để demo flow, thử interaction và rehearsal selector
- dùng `build` để chắc route và component không bị vỡ khi đóng gói

### `apps/docs`

Chạy riêng tài liệu Quartz:

```bash
pnpm run docs:dev
pnpm --filter docs build
pnpm --filter docs format
pnpm --filter docs exec npm run check
```

Ghi chú:

- `docs:dev` dùng để serve tài liệu khi đang viết spec/test case
- `build` build static site từ nội dung trong `apps/docs`
- `format` format tài liệu và mã trong app docs
- `check` là script riêng của `apps/docs`, nên gọi qua `pnpm --filter docs exec npm run check`

### `packages/ui`

Làm việc riêng với shared UI package:

```bash
pnpm --filter @workspace/ui lint
pnpm --filter @workspace/ui format
pnpm --filter @workspace/ui typecheck
```

Khi dùng:

- sau khi thêm component shadcn mới
- sau khi đổi token style hoặc utility shared
- trước khi dùng component mới trong `web` hoặc `playground`

### E2E Test

Chạy riêng phần Playwright:

```bash
pnpm run e2e:install
pnpm run e2e:list
pnpm run e2e
pnpm run e2e:web
pnpm run e2e:playground
```

Khi dùng:

- `e2e:install`: cài browser cho Playwright
- `e2e:list`: liệt kê tất cả test Playwright hiện có
- `e2e`: chạy toàn bộ test
- `e2e:web`: chỉ chạy test cho app `web`
- `e2e:playground`: chỉ chạy test cho app `playground`

## E2E Test Với Playwright

Repo hiện có Playwright starter cho luồng login ở cả `web` và `playground`.

Nếu muốn gọi trực tiếp Playwright thay vì script trong `package.json`:

```bash
pnpm exec playwright test --list
pnpm exec playwright test --project=web
pnpm exec playwright test --project=playground
```

### Cấu Trúc E2E

```text
tests/e2e/
├── README.md
├── login-flow.spec.ts
└── pages/
    └── login-flow.page.ts
```

Nguyên tắc:

- mỗi luồng nghiệp vụ nên có một file spec riêng
- dùng `data-testid` ổn định trong UI
- dùng Page Object Model cho phần tương tác dùng lại nhiều lần

## Tài Liệu Trong Quartz

Tài liệu hiện nằm trong:

- [apps/docs/content/index.md](/Users/test/Develop/build-app-with-ai/apps/docs/content/index.md)
- [apps/docs/content/spec-login-flow.md](/Users/test/Develop/build-app-with-ai/apps/docs/content/spec-login-flow.md)
- [apps/docs/content/test-case-login-flow.md](/Users/test/Develop/build-app-with-ai/apps/docs/content/test-case-login-flow.md)

Đây là ví dụ cho một flow đầy đủ:

- spec
- acceptance criteria
- test case
- UI ở `playground`
- implementation ở `web`
- E2E automation trong `tests/e2e`

## Shared UI

Shared UI nằm trong `packages/ui`.

Ví dụ import:

```tsx
import { Button } from "@workspace/ui/components/button"
import { Input } from "@workspace/ui/components/input"
import { Card } from "@workspace/ui/components/card"
```

Global style dùng chung:

```tsx
import "@workspace/ui/globals.css"
```

## Data Test ID Convention

Để Playwright ổn định hơn, repo đang dùng quy ước:

- `web-*` cho app `web`
- `playground-*` cho app `playground`

Ví dụ:

- `web-login-form`
- `web-login-submit`
- `playground-login-form`
- `playground-login-success-page`

Khi thêm flow mới, nên giữ naming nhất quán:

- `<app>-<flow>-<element>`

Ví dụ:

- `web-signup-email-input`
- `playground-checkout-submit`

## Khi Thêm Feature Mới

Khuyến nghị checklist:

1. Tạo hoặc cập nhật spec trong `apps/docs/content`
2. Viết acceptance criteria rõ ràng
3. Viết test case tương ứng
4. Dựng flow trong `apps/playground` nếu cần review sớm
5. Triển khai trong `apps/web`
6. Dùng shared component từ `packages/ui` nếu hợp lý
7. Gắn `data-testid` cho các điểm cần automation
8. Thêm hoặc cập nhật Playwright test
9. Chạy `typecheck`, `lint`, và E2E liên quan

## TODO Comments

> TODO: Các hạng mục dưới đây chỉ là backlog kỹ thuật và vận hành, chưa phải phần đã triển khai trong repo.
> Ưu tiên: `P1` = nên làm sớm, `P2` = nên lên kế hoạch, `P3` = nghiên cứu hoặc triển khai sau.

### Skills

- [ ] TODO P1: Tạo thư mục skills dùng chung cho team, ví dụ `skills/`.
- [ ] TODO P1: Chia skills theo vai trò `PO`, `BA`, `DEV`, `TESTER`.
- [ ] TODO P1: Chuẩn hóa nội dung mỗi skill gồm mục tiêu công việc, input kỳ vọng, output mong muốn, checklist review và template dùng lại.
- [ ] TODO P2: Xây convention đặt tên cho skills, ví dụ `skills/po/feature-spec`, `skills/ba/acceptance-criteria`, `skills/dev/implementation-plan`, `skills/tester/test-case-design`.

### Production Build

- [ ] TODO P1: Thiết kế cơ chế chỉ giữ `data-testid` ở môi trường dev/test.
- [ ] TODO P1: Khi build production cần strip hoặc disable `data-testid` để giảm noise ở DOM.
- [ ] TODO P2: Đánh giá các hướng strip `data-testid` như Babel/SWC transform, wrapper helper cho test id, hoặc condition theo `NODE_ENV`.
- [ ] TODO P1: Đảm bảo E2E test ở môi trường test vẫn có selector ổn định sau khi xử lý `data-testid`.

### Claude Commands

- [ ] TODO P2: Tạo bộ command mẫu cho người dùng có kinh nghiệm làm việc với Claude hoặc CLI agent khác.
- [ ] TODO P2: Ưu tiên command cho các tác vụ lặp lại như sinh spec từ feature brief, sinh acceptance criteria, dựng test case từ spec, tạo skeleton flow trong `playground`, và review coverage giữa docs, code, test.
- [ ] TODO P2: Quy định nơi lưu command rõ ràng, ví dụ `commands/` hoặc `apps/docs/content/commands/`.

### MCP

- [ ] TODO P2: Bổ sung một số MCP phù hợp với workflow của repo.
- [ ] TODO P3: Ưu tiên MCP cho docs/knowledge retrieval, design/asset lookup, issue tracker/project management, test automation/browser tooling, và backend schema hoặc API inspection.
- [ ] TODO P2: Trước khi thêm MCP, xác định rõ ai là người dùng chính, MCP hỗ trợ bước nào trong flow `spec -> playground -> web -> test`, và đầu ra có được đưa lại vào docs hoặc code review process hay không.

## Lưu Ý Thực Tế

- `playground` là nơi thử nghiệm và review, không nên chứa logic production phức tạp.
- `web` là nơi ưu tiên implementation thật.
- `docs` nên là nơi mô tả kỳ vọng nghiệp vụ, không chỉ là ghi chú rời rạc.
- `data-testid` nên ổn định và không đổi theo text UI.
- Nếu form chỉ là demo flow, nên tránh submit dữ liệu nhạy cảm qua query string.

## Trạng Thái Hiện Tại Của Repo

Repo hiện đã có một flow đăng nhập mẫu chạy xuyên suốt:

- docs/spec
- playground prototype
- web implementation
- Playwright E2E

Flow này có thể dùng làm template cho các feature tiếp theo.

## Gợi Ý Mở Rộng

Các bước hợp lý tiếp theo:

- thêm nhiều flow hơn như signup, forgot password, onboarding
- thêm CI chạy Playwright
- chuẩn hóa template spec/test case trong `apps/docs`
- mở rộng `packages/ui` thành design system rõ ràng hơn
- thêm mock API hoặc fake auth layer cho flow phức tạp hơn

## Ghi Chú Cuối

Nếu anh/chị coi repo này là “hệ điều hành” cho quy trình làm sản phẩm, thì vai trò của từng phần nên luôn rõ:

- `docs` trả lời: cần xây cái gì và vì sao
- `playground` trả lời: trải nghiệm sẽ trông như thế nào
- `web` trả lời: hệ thống thật được triển khai ra sao
- `tests/e2e` trả lời: luồng đó có đang hoạt động đúng không

README này nên tiếp tục được cập nhật khi repo mở rộng thêm app, package, flow và quy ước mới.

build-app-with-ai

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README