Skip to content

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 ​

pnpm + Nx — TypeScriptpub workspace — Dartcode/ — một repo, ba hệ sinh tháiapps/apiDeno, ngoài workspaceapps/web-adminapps/web-storybookapps/web-documentpackages/web-ui · web-services · web-constants · web-localizationvitest · tsc · Nx affected + cachemột lockfile: pnpm-lock.yamlapps/app-userapps/app-saleapps/app-widgetbookpackages/app-core · services · features · ui · localization · pipointflutter test · dart analyze · Nxmột lockfile: pubspec.lockapps/api nằm NGOÀI pnpm workspace (Deno, vendor riêng) · app-sale đang tạm dừng

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áiQuản lý bởiLockfile
TypeScript — web app và package dùng chungpnpm workspace + Nxcode/pnpm-lock.yaml
Dart — hai app Flutter và package pi_*pub workspace + Nxcode/pubspec.lock
Deno — backend apps/apiDeno, cố ý nằm ngoài pnpm workspacedeno.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 ​

Client3 ứng dụng/rest/v1Data API tự động/graphql/v1GraphQL tự độngbảng PostgreSQLtruy cập trực tiếpEdge Functionlối vào duy nhấtBa đường gạch chéo đều TẮT trên mọi project

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 ​

accountsCUSTOMERkhách hàngSTAFFnhân viên Web AdminAPP_USERAPP_SALEWEB_ADMINrole: userrole: salerole: …app_membershipsrole_assignmentsKhoá duy nhất là (số điện thoại, loại tài khoản) — một người có thể có cả hai

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.

→ Ma trận quyền

3. Hợp đồng sinh ra, không viết tay ​

schema:exportcodegencodegendocgenSDL TypeScriptdomains/*/schema.tsschema.graphqlmột file, được commit@pi/web-servicesgenerated.tspi_services*.graphql.dartweb-documenttrang tra cứu APIKhông ai sửa tay schema.graphql hay file sinh ra.Kiểu client cần mà schema chưa có = thay đổi backend trước.Cả hai client đọc FILE đã export, không đọc server đang chạy.

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ốngKết quả
Cùng khoá, cùng payloadTrả lại kết quả đã lưu, status: REPLAYED — không chạy lần hai
Cùng khoá, payload khácconflict / idempotency_key_reuse
Khoá đang chạyconflict / 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.

→ Hàm SQL · 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:

một pull request1 · backendSDL · resolver · service · migration2 · hợp đồngschema:export → codegen3 · quyềnpermission-matrix.json4 · web, 5 · mobileroute · trang · operation6 · tài liệudocgen — tự cập nhậtNă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 viết tay.

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.

→ Thêm một API

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 routeWeb dùng ROUTING_PATH, mobile dùng PiRoutes
Không có chữ hiển thị trong codeWeb dùng t(), mobile dùng slang; kit nhận chữ qua props
UI chỉ lấy từ kitWeb: @pi/ui. Mobile: pi_ui
Tiếng Việt là ngôn ngữ gốcvi là nguồn chuẩn có kiểu, en được kiểm theo nó
File sinh ra được commitschema.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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17