Giao diện
Kiến trúc chung
Trang này nói về những gì đúng cho cả ba phần — backend, web, mobile. Chi tiết riêng từng phần ở Back-end, Front-end, Mobile.
Một repo, ba hệ sinh thái
Toàn bộ mã nguồn nằm trong một repository, chia làm hai thư mục cấp một: code/ (mã) và docs/ (tài liệu nghiệp vụ và kỹ thuật).
code/ là monorepo Nx trên pnpm workspace, nhưng không phải mọi thứ trong đó đều là package của pnpm:
| Hệ sinh thái | Quản lý bởi | Lockfile |
|---|---|---|
| TypeScript — web app và package dùng chung | pnpm workspace + Nx | code/pnpm-lock.yaml |
Dart — hai app Flutter và package pi_* | pub workspace + Nx | code/pubspec.lock |
Deno — backend apps/api | Deno, cố ý nằm ngoài pnpm workspace | deno.lock |
Vì sao apps/api đứng ngoài. Nó là dự án Deno; deno.json đặt nodeModulesDir: auto để Deno không leo lên code/package.json. Các gói jsr: được vendor sẵn trong apps/api/vendor/ vì jsr.io trả 403 từ Việt Nam — thêm hoặc nâng một gói jsr: phải vendor lại từ mạng truy cập được.
Vì sao một repo thay vì nhiều repo. Hợp đồng giữa các phần — schema GraphQL, mã lỗi, tên quyền — thay đổi theo từng tính năng. Một repo cho phép một pull request đổi cả ba phía cùng lúc, và CI kiểm được rằng chúng vẫn khớp nhau. Tách repo thì mỗi thay đổi hợp đồng thành ba PR và một cuộc hẹn.
Nx dùng để làm gì. Không phải để build — mỗi hệ sinh thái tự build bằng công cụ của nó. Nx làm hai việc: chạy đúng tác vụ của đúng project (nx serve, nx test), và chỉ chạy lại thứ bị ảnh hưởng (nx affected), có cache theo nội dung. Nhờ đó quality gate chỉ chạy phần liên quan tới thay đổi.
Sáu khái niệm xuyên suốt
1. Edge Function là lối vào duy nhất
API tự động của Supabase tắt trên mọi project. Không client nào — web, mobile, hay script — chạm được vào bảng. Mọi lối vào là một Edge Function do dự án viết, review qua pull request và nằm trong Git.
Hệ quả thiết kế: thay đổi schema không bao giờ vô tình mở ra một API mới. Đây là lý do chính của luật này, không phải vì hiệu năng.
→ Back-end
2. Một người, nhiều ứng dụng, quyền theo từng ứng dụng
Khách hàng có một tài khoản CUSTOMER dùng cho cả User App và Sale App, mỗi app một membership với trạng thái riêng. Nhân viên Web Admin là tài khoản STAFF tách biệt — cùng số điện thoại vẫn được, vì khoá duy nhất là cặp (số điện thoại, loại tài khoản).
Mọi request mang header x-pi-app, và header đó phải trùng app trong token. Nó chọn membership nào được đọc; nó không bao giờ là tham số phân quyền.
Quyền hiệu lực đọc lại ở mỗi request — token không chứa vai trò hay quyền. Nên thu hồi quyền có hiệu lực ngay, không chờ token hết hạn.
3. Hợp đồng sinh ra, không viết tay
Không ai sửa tay schema.graphql hay file sinh ra. Một kiểu dữ liệu client cần mà schema chưa có là một thay đổi backend trước. Cả hai client đọc file đã export, không đọc server đang chạy — nên codegen chạy được khi offline và kết quả tất định.
File sinh ra được commit, để diff hợp đồng hiện ra trong review.
4. Lỗi là mã ổn định, không phải câu chữ
Mọi lỗi mang một extensions.code trong danh sách cố định. Client chỉ rẽ nhánh theo mã, không bao giờ parse message. Lỗi không mang mã nào trong danh sách ra khỏi server dưới dạng internal với message cố định — không rò message gốc, SQL, stack hay secret.
Cùng bộ mã đó dùng cho Edge Function không phải GraphQL, trong { error: { code, message, details } }.
Mobile đẩy nguyên tắc này đi xa hơn: lỗi là giá trị (Result / PiFailure), không phải exception, và chỉ có hai chỗ trong toàn app được bắt exception.
→ Mã lỗi
5. Ghi là idempotent và có phiên bản
Mọi mutation nhận requestId do client sinh, làm khoá idempotency theo (người gọi, operation, requestId):
| Tình huống | Kết quả |
|---|---|
| Cùng khoá, cùng payload | Trả lại kết quả đã lưu, status: REPLAYED — không chạy lần hai |
| Cùng khoá, payload khác | conflict / idempotency_key_reuse |
| Khoá đang chạy | conflict / request_in_progress |
Sửa bản ghi đã có thì phải gửi expectedVersion; lệch thì stale_version. Hai người sửa cùng lúc không ghi đè nhau im lặng.
Điều này quan trọng vì mạng di động: một request thành công nhưng mất phản hồi sẽ được thử lại, và lần thử lại không được tạo đơn thứ hai.
6. Bất biến quan trọng nằm trong database
Phần lớn quy tắc về tiền và trạng thái không nằm trong TypeScript mà trong hàm SQL SECURITY DEFINER. Lý do: một transaction trong database là nơi duy nhất giữ được bất biến khi nhiều request chạy đồng thời.
TypeScript điều phối; SQL giữ sự thật. RLS là lớp phòng thủ thứ hai — bốn role mà Edge Function dùng để kết nối đều không bỏ qua RLS.
Một tính năng đi qua ba phần như thế nào
Ví dụ thêm một thao tác Admin:
Năm bước đầu nằm trong một pull request, vì chúng phải khớp nhau. Bước sáu không phải viết tay.
Quy ước chung cho cả ba phần
| Quy ước | Áp dụng |
|---|---|
Tên file kebab-case, kể cả Dart (sign-in-screen.dart) | Cả repo. Hai ngoại lệ do công cụ bắt buộc: *_test.dart và file sinh *.g.dart |
| Không viết thẳng đường dẫn route | Web dùng ROUTING_PATH, mobile dùng PiRoutes |
| Không có chữ hiển thị trong code | Web dùng t(), mobile dùng slang; kit nhận chữ qua props |
| UI chỉ lấy từ kit | Web: @pi/ui. Mobile: pi_ui |
| Tiếng Việt là ngôn ngữ gốc | vi là nguồn chuẩn có kiểu, en được kiểm theo nó |
| File sinh ra được commit | schema.graphql, generated.ts, *.graphql.dart, và cả tài liệu này |
Môi trường và phát hành
Bốn môi trường đang dùng (local, dev, staging, uat) deploy từ cùng một thư mục supabase/ trong Git; chỉ cấu hình, secret và dữ liệu khác nhau. Production chưa được tạo.
Local không dùng Docker: Edge Function là server Deno thường nên chạy trực tiếp, PostgreSQL 17 chạy native.
→ Môi trường & triển khai · Chạy local
Nguồn: CLAUDE.md, docs/technical/01-back-end-supabase.md, 02-environment.md, 04-front-end.md, 12-mobile-architecture.md, docs/contracts/api-conventions.md. Trang viết tay — xem mức độ tin cậy.