BeaChoice là một monorepo gồm các ứng dụng triển khai độc lập, dùng chung một API NestJS, một cơ sở dữ liệu Postgres và một dịch vụ xác thực. Trang này tóm tắt bức tranh chung; chi tiết từng phần nằm ở docs/system-architecture.md trong repo.
Sơ đồ
Phần tiêu đề “Sơ đồ”flowchart TB subgraph Clients W["apps/web<br/>Next.js · khách"] S["apps/salon<br/>Next.js · chủ salon"] A["apps/admin<br/>Next.js · quản trị"] M["apps/mobile<br/>Flutter · khách và salon"] end AU["apps/auth<br/>Better Auth"] API["apps/api<br/>NestJS · /api/v2"] DB[("Postgres 17<br/>+ pg-boss")] R2[("Object storage<br/>ảnh, video")] SP["SePay<br/>thanh toán"] W --> API S --> API A --> API M --> API W --> AU S --> AU A --> AU M --> AU API --> DB API --> R2 SP -- webhook --> APICác thành phần
Phần tiêu đề “Các thành phần”| Thành phần | Vai trò |
|---|---|
apps/api |
Logic nghiệp vụ, lưu trữ, tác vụ nền (pg-boss), tích hợp ngoài |
apps/auth |
Đăng nhập, tổ chức (salon), 2FA, cấp JWT ngắn hạn |
apps/web |
Trang công khai và luồng đặt lịch của khách |
apps/salon |
Ứng dụng web cho chủ salon và quản lý |
apps/admin |
Console quản trị nền tảng, sau lớp truy cập riêng |
apps/mobile |
Ứng dụng Flutter cho khách và salon |
apps/docs |
Trang tài liệu này |
packages/contracts |
Schema zod, danh mục lỗi, sự kiện, đặc tả OpenAPI |
Quyết định cần biết khi tích hợp
Phần tiêu đề “Quyết định cần biết khi tích hợp”- Hợp đồng trước, mã sau. Schema zod trong
packages/contractslà nguồn duy nhất cho DTO, lỗi và OpenAPI. Xem OpenAPI. - Tenant là salon. Mã tổ chức bằng mã salon. Các đường dẫn
/v2/salon/*lấy salon từ claim của JWT, không từ đường dẫn. - JWT ngắn hạn. Ứng dụng web giữ phiên bằng cookie ở máy chủ của chính nó; JWT sống năm phút và chỉ được đổi ở phía máy chủ, không xuống trình duyệt.
- Tiền là số nguyên đồng. Mọi số tiền lưu bằng số nguyên, đơn vị đồng.
- Hai luồng thanh toán tách bạch. Phí gói đi vào tài khoản của nền tảng, cọc đi vào tài khoản của từng salon. Nền tảng không giữ tiền cọc.
- Lỗi theo RFC 9457. Phản hồi lỗi là
application/problem+jsonvới trườngcodeổn định để xử lý bằng chương trình. - Trang HTML nhận CSP theo từng yêu cầu. Trang web dùng nonce, vì vậy không có trang HTML tĩnh dùng chung cho mọi người.