Tổng quan

Bốn nhóm tài liệu: tổng quan, hướng dẫn kỹ thuật, database, hướng dẫn sử dụng.

Slide Deck Mode

Mục tiêu bộ tài liệu

  • Mỗi menu là một tài liệu độc lập, dễ dùng khi họp hoặc onboarding.
  • Mỗi tài liệu trình bày theo slide ngắn gọn, tập trung quyết định và thao tác.
  • Nội dung đã đối chiếu từ source thực tế trong workspace.

Hệ sinh thái GOHUB

User Channels:
- gohub.vn (Next.js storefront VN)
- gohub.com (Next.js storefront global, multi-locale)
- gohub-app (Flutter mobile)

Admin Channels:
- gohub-admin (React + Vite, backoffice vận hành)
- gohub-product-admin (React + Vite, backoffice sản phẩm)

Backend:
- gohub-product-api (Express + Prisma + PostgreSQL)
- GOHUB API core (domain api.gohub.com / api.stg-space.gohub.com)

Mapping domain hiện tại

Dịch vụStagingProduction
GOHUB APIapi.stg-space.gohub.com -> 34.59.152.45api.gohub.com -> TBD
GOHUB Adminadmin.stg-space.gohub.com (Cloudflare)admin.space.gohub.com (Cloudflare)
GOHUB VNvn.stg-space.gohub.com -> 34.59.152.45gohub.vn -> TBD
GOHUB COMcom.stg-space.gohub.com -> 34.59.152.45gohub.com -> TBD
PM + API PMpm.stg-space.gohub.com (Cloudflare), api-pm.stg-space.gohub.com -> 34.124.129.187pm.space.gohub.com (Cloudflare), api-pm.space.gohub.com -> TBD

System Landscape

Phân tách theo trust boundary: kênh công khai (B2C) và công cụ nội bộ (staff) là hai nhóm client; phía sau là dịch vụ HTTP và nền tảng dữ liệu / edge. Tên artifact thống nhất kiểu repo / service.

① · BOUNDARY — PUBLIC

Kênh khách hàng

User ngoài biên, không xác thực nội bộ admin

RepositoryStack & ghi chú
gohub-vn
Next.js 16 · storefront VN
dev :3006
gohub-com
Next.js 16 · đa ngôn ngữ
dev :3005
gohub-app
Flutter · GetX · Dio · gọi REST
Next.jsReact 19Flutter
② · BOUNDARY — INTERNAL

Console nội bộ

Nhân sự vận hành / product; SPA tách biệt storefront

RepositoryVai trò & tích hợp
gohub-admin
React · Vite 7 · SPA
Gọi Core API (VITE_API_URL) · refresh /admin/auth/refresh
gohub-product-admin
React · Vite 7 · SPA
Core API + Product API (cấu hình env tách auth / product)
Vite 7TanStack QueryCloudflare Pages
③ · APPLICATION SERVICES

Dịch vụ backend

HTTP stateless; tách domain Core vs Product (PM)

Service / repoNhiệm vụ
gohub-api
Core business API (triển khai service)
Host tham chiếu: api.gohub.com
gohub-product-api
Express · Prisma · Postgres
OpenAPI /api-docs · health /health
RESTNodePrisma
④ · PLATFORM

Dữ liệu & edge

Tách DB theo bounded context; Cloudflare không thay thế API

Thành phầnMô tả
postgres · core
Dữ liệu GOHUB Core
Gắn với gohub-api
postgres · pm
Dữ liệu catalog & PM
Gắn với gohub-product-api
cloudflare
DNS · SSL · proxy edge
Host admin / pm (không host trực tiếp DB)
PostgreSQLDNS/SSLEdge

Architecture Diagram (AWS-style reference)

Luồng trái → phải giống AWS Architecture Center: Internet / edge managed → tier ứng dụng → API → datastore. Màu cam: lớp edge; xanh đậm: dữ liệu.

GOHUB — Logical reference (single environment) Internet HTTPS từ browser / mobile app Edge (kiểu CloudFront / CDN) — triển khai: Cloudflare DNS · SSL/TLS · proxy · caching (một phần hostname admin / pm) Managed edge Application tier (SPA / SSR / mobile client) Public clients (B2C) gohub-vn Next.js · SSR/store gohub-com Next.js · i18n gohub-app Flutter · REST Internal consoles (staff) gohub-admin Vite SPA → gohub-api gohub-product-admin Vite SPA → Core + product API REST / JSON API tier (compute — tương đương ALB + services) gohub-api Core domain · api.gohub.com gohub-product-api Express · Prisma · PM domain Data tier (Amazon RDS–style) · PostgreSQL postgres · core postgres · pm ORM / pool từ gohub-api · gohub-product-api

Domain & Routing Map

Dịch vụStagingProduction
GOHUB APIapi.stg-space.gohub.com -> 34.59.152.45api.gohub.com -> TBD
GOHUB Adminadmin.stg-space.gohub.com (Cloudflare)admin.space.gohub.com (Cloudflare)
GOHUB VNvn.stg-space.gohub.com -> 34.59.152.45gohub.vn -> TBD
GOHUB COMcom.stg-space.gohub.com -> 34.59.152.45gohub.com -> TBD
PM + API PMpm.stg-space.gohub.com (Cloudflare), api-pm.stg-space.gohub.com -> 34.124.129.187pm.space.gohub.com (Cloudflare), api-pm.space.gohub.com -> TBD

Frontend Platforms

  • gohub-vn: Next.js 16, dev port 3006, Docker + GAR pipeline.
  • gohub-com: Next.js 16 đa ngôn ngữ, dev port 3005, Docker + GAR pipeline.
  • gohub-admin: React 19 + Vite 7, deploy Cloudflare Pages project gohub-admin.
  • gohub-product-admin: React 19 + Vite 7, deploy Cloudflare Pages cho main và staging.
  • gohub-app: Flutter app, build IPA/AAB qua script theo env.

Backend Services

  • gohub-product-api: Node 20+, Express 4, Prisma 7, Postgres adapter.
  • Module chính: /product-master, /pm-listing, /pm-item, /pm-sku, /vendors, /countries.
  • OpenAPI UI: /api-docs, health check: /health.
  • GOHUB API core phục vụ luồng storefront + admin core domain.

Data & Integration

Data Domain

  • Core domain -> DB GOHUB.
  • PM domain -> DB GOHUB PM.
  • Tách domain giúp kiểm soát ownership và scale.

Integration

  • Product API có route sync nhóm /lark-*.
  • Storefront tích hợp payment/auth qua endpoint backend.
  • Mobile dùng REST API qua --dart-define.

Deployment Pipelines

  • Admin portals: GitHub Actions -> Wrangler -> Cloudflare Pages.
  • Storefront web: GitHub Actions -> Docker build -> Google Artifact Registry.
  • Product API: Dockerfile + docker-compose (staging/prod).
  • Mobile app: script build theo profile dev/stg/prod (IPA/AAB).

Environment Matrix & Risks

NhómBiến chínhRủi ro cần kiểm
AdminVITE_API_URL, VITE_AUTH_API_URL, VITE_PRODUCT_API_URLSai endpoint dẫn tới lỗi auth/cross-domain
StorefrontNEXT_PUBLIC_API_URL, NEXT_SERVER_API_URLLệch public/server API gây sai data runtime
Product APIDATABASE_URL, AUTH_SERVICE_URLKết nối DB/auth fail ở runtime
MobileDEV_API_URL, PROD_API_URL qua --dart-defineBuild nhầm env trước release store

gohub-admin

  • React 19 + Vite + TS, React Router v7, React Query, Zustand, i18next.
  • API base URL: VITE_API_URL, refresh token qua /admin/auth/refresh.
  • Nhiều module vận hành: orders, products, promotions, posts, report, settings.
  • CI deploy Cloudflare Pages project gohub-admin.

gohub-product-admin

  • React 19 + Vite + TS, route tập trung cho product/master-data/guide.
  • API dùng bộ biến VITE_API_URL, VITE_AUTH_API_URL, VITE_PRODUCT_API_URL.
  • Màn hình trọng tâm: PM listing/item/SKU, categories, vendors, countries, operators.
  • Deploy Cloudflare Pages cho cả branch main và staging.

gohub-product-api

  • Express + Prisma, env bắt buộc DATABASE_URL, có auth service URL riêng.
  • Route chính: /pm-listing, /pm-item, /pm-sku, /product-master...
  • Lark sync endpoints có sẵn: /lark-*.
  • Deploy containerized, expose mặc định port 3003.

gohub-vn và gohub-com

  • Cả hai là Next.js storefront; VN tập trung thị trường nội địa, COM tập trung multi-locale.
  • gohub-com có routing /[locale], i18n JSON, sitemap theo locale.
  • Hai repo đều có Docker + workflow build/push image lên GAR.
  • Port local: VN 3006, COM 3005.

Hai database logic theo 2 API

Mỗi API backend gắn một (hoặc một cụm) PostgreSQL riêng. Tài liệu dưới đây bám trực tiếp source có trong workspace.

NguồnAPI / serviceDB & công cụSource of truth trong repo
1 · Product / PM gohub-product-api (Express, ví dụ domain api-pm.*) PostgreSQL — Prisma Client + adapter @prisma/adapter-pg, pool pg gohub-product-api/prisma/schema.prisma, src/core/database/db.ts, prisma/migrations/
2 · GOHUB Core Backend phục vụ gohub-admin, storefront qua BFF (ví dụ api.stg-space.gohub.com / api.gohub.com) PostgreSQL (tách instance; schema không có trong monorepo này) Chỉ tham chiếu hợp đồng API (env VITE_API_URL trong admin). Cần bổ sung từ team sở hữu repo Core.

Database 1 — Product API (chi tiết từ source)

  • Kết nối: biến DATABASE_URL (bắt buộc), pool tối đa mặc định 50 (trần 100), idle timeout cấu hình qua env — xem src/core/database/db.ts, src/core/config/env.ts.
  • Schema: một datasource PostgreSQL duy nhất; toàn bộ bảng khai báo trong prisma/schema.prisma (generator prisma-client-js).
  • Thay đổi cấu trúc: chỉ qua migration versioned trong prisma/migrations (kèm seed tùy chọn prisma/seed.ts trong config).
  • Phạm vi nghiệp vụ: master data (category, country, operator, platform, listing…), catalog sản phẩm (product master/variant, product list), topup, đồng bộ Lark Base (lark_*), màn PM (pm_*), audit (audit_logs), tích hợp vendor / third-party token.

Các nhóm bảng chính (Product API)

Tên bảng theo @@map trong Prisma — dùng làm data dictionary ngắn.

NhómBảng tiêu biểuGhi chú
Master & danh mụccategories, countries, support_countries, currencies, operators, platforms, listings, specs, common_optionsPlatform → Listing → Product list; specs dùng chung cho master / variant / list variant.
Vendor & đối tácvendors, vendor_tokens, third_party, third_party_tokenToken API partner / third-party tách bảng.
Catalog sản phẩmproduct_master, product_vendor, product_variants, product_groups, product_group_variants, product_master_specs, product_variant_specsClone vendor view product_vendor; variant gắn product_code / tenant.
Kênh & giá listproduct_lists, product_list_variants, product_list_variant_specsPK composite list variant; pricing theo list.
Topupproduct_topup, product_variant_topupsGói topup + liên kết variant.
Lark & PM mirrorlark_product, lark_sku, lark_listing, lark_item, lark_country; pm_product, pm_sku, pm_listing, pm_itemMirror cột từ Lark Base; pm_* có cờ sync (manual vs sync).
Auditaudit_logsJSON old/new, index theo bảng + record.

Database 2 — GOHUB Core API

  • Vai trò: domain vận hành chung (ví dụ auth admin, đơn hàng, bài viết, cấu hình tenant/site, upload…) phục vụ gohub-admin và các client gọi REST qua base URL production (https://api.gohub.com/v1 trong workflow deploy admin).
  • Schema: không có file Prisma/SQL trong workspace hiện tại — không liệt kê bảng ở đây để tránh sai lệch. Cần đồng bộ với team backend Core (connection string, ERD, migration policy).
  • Phân tách với Product API: dữ liệu catalog/PM nằm DB Product; dữ liệu giao dịch / nội dung / người dùng hệ thống theo ranh giới API Core (đối chiếu endpoint thực tế trên staging trước khi ghi tài liệu chi tiết).

Tech Guide — submenu và phân vùng dữ liệu

Mỗi mục 02.x / 03 mô tả kiến trúc hoặc repo; cột “phân vùng DB” chỉ ra khi đọc tài liệu đó cần nhớ DB nào.

SubmenuTrọng tâm tài liệuPhân vùng DB / gợi ý bảng
02.1 System LandscapeRanh giới app · API · nền tảngCả hai: phân biệt service nào gọi Product DB vs Core DB (không trộn connection).
02.2 Architecture DiagramEdge → App → API → DataHai node PostgreSQL tách: catalog/PM vs vận hành chung.
02.3 Domain & Routing MapHostname, môi trườngCùng phân vùng logic; DATABASE_URL / secret theo env (staging ≠ prod).
02.4 Frontend PlatformsStorefront, admin FEFE không nối DB trực tiếp; dữ liệu đổ về đúng API → đúng phân vùng.
02.5 Backend Servicesproduct-api vs core APIProduct DB (Prisma) · Core DB (ngoài repo).
02.6 Data & IntegrationĐồng bộ Lark, tích hợpChủ yếu Product DB: lark_*, pm_*, common_options, audit_logs.
02.7 Deployment PipelinesBuild / deployMigration chỉ trong pipeline gohub-product-api; Core tách pipeline/secret.
02.8 Environment Matrix & RisksMa trận envHai dòng secret DB độc lập (Product vs Core); rủi ro trộn env.
03. Source CatalogRepo, đường dẫn sourceSchema: gohub-product-api/prisma/schema.prisma.

User Guide & Tổng quan

SubmenuTrọng tâmPhân vùng DB
Tổng quanBản đồ hệ sinh thái, domainTham chiếu cả hai phân vùng ở mức domain (chưa chi tiết bảng Core).
05. GOHUB Admin SOPBackoffice vận hànhThao tác qua API Core → Core DB (auth, đơn, nội dung, cấu hình…).
06. Product Admin SOPPM, catalog, publishProduct DB: product_*, pm_*, master/listing/item.

Cách đọc: khi viết runbook hoặc RCA, lấy đúng phân vùng theo cột thứ ba — tránh giả định một DB duy nhất.

Quy tắc vận hành & cập nhật tài liệu

  • Product API: mọi thay đổi schema qua migration + review; không sửa trực tiếp production ngoài quy trình.
  • Sau mỗi release thay đổi schema.prisma, cập nhật lại slide “nhóm bảng” và bảng ánh xạ submenu nếu có bảng / luồng mới.
  • Core API: khi có repo schema hoặc ERD chính thức, bổ sung vào slide 04.3 và một dòng tương ứng trong 04.4.
  • Connection string & host cụ thể theo môi trường: chỉ lưu trong secret / vault, không ghi vào tài liệu công khai.

Nhóm case chính

  • Quản lý tài khoản và phân quyền nội bộ.
  • Quản lý nội dung/cấu hình hệ thống.
  • Theo dõi vận hành đơn hàng, đối tác, campaign/promotion.
  • Rà soát báo cáo vận hành định kỳ.

SOP chuẩn theo case

  1. Xác định mục tiêu nghiệp vụ và phạm vi tác động.
  2. Kiểm tra permission trước thao tác.
  3. Nếu thao tác rủi ro cao: test trên staging trước.
  4. Ghi ticket + log thao tác.
  5. Đối chiếu UI, API và audit log sau khi hoàn thành.

Template mô tả thao tác

  • Case: Khóa tài khoản user
  • Mục đích: Ngăn truy cập rủi ro
  • Bước chính: User Management -> Search -> Lock -> Confirm
  • Kết quả kiểm tra: user không login được, audit log có bản ghi

Nhóm nghiệp vụ PM

  • Quản lý product master, listing, item, SKU.
  • Quản lý category/vendor/platform/country/operator/currency.
  • Publish/unpublish nội dung sản phẩm.
  • Theo dõi đồng bộ API PM và dữ liệu hiển thị storefront.

SOP thao tác PM

  1. Chọn đúng môi trường (staging hoặc prod).
  2. Luồng chuẩn: Save Draft -> Verify -> Publish.
  3. Với thay đổi diện rộng: thông báo ticket cho team liên quan.
  4. Kiểm tra phản hồi từ API PM sau cập nhật.
  5. Ghi log thay đổi (ai, thời điểm, nội dung).

Checklist vận hành tuần

  • Rà soát thay đổi schema và đồng bộ docs.
  • Kiểm tra lệch dữ liệu giữa PM Admin và API PM.
  • Cập nhật case mới vào SOP nếu có issue thực tế.
  • Xác nhận owner/backup owner cho từng nhóm màn hình.
Slide 1/3