System Overview: GoTrace / HanoiTrace (Gotrace-portal)

1. Giới thiệu Chung & Định vị Sản phẩm

Gotrace-portal là nền tảng phần mềm Supply Chain Traceability (Truy xuất Nguồn gốc Chuỗi cung ứng), Quản lý An toàn Thực phẩm (ATTP), Bếp ăn Học đường và Government Oversight (Giám sát Quản lý Nhà nước) do Zam Tech Việt Nam phát triển.

Điểm đặc biệt trong kiến trúc của Gotrace-portal là khả năng vận hành Multi-Brand Architecture trên cùng một codebase duy nhất thông qua biến môi trường NEXT_PUBLIC_BRAND:

Brand (NEXT_PUBLIC_BRAND)	Tên hiển thị	Đối tượng & Phạm vi Phục vụ	Đặc thù Nghiệp vụ & Tích hợp (platform_type)
gotrace (Default)	GoTrace	Nền tảng SaaS thương mại phục vụ doanh nghiệp sản xuất, chế biến, phân phối, trường học trên toàn quốc	Hỗ trợ doanh nghiệp platform_type = 'GOTRACE' tự động phát hành W3C Verifiable Credentials (Ed25519) và neo bằng chứng (Merkle Root Anchoring) lên Spores Blockchain mà không bắt buộc phải có sẵn token/did/gcp của cổng NDA cũ.
hanoitrace	HanoiTrace	Hệ thống Quản lý Truy xuất Nguồn gốc & An toàn Thực phẩm Thành phố Hà Nội	Phục vụ đồng thời Doanh nghiệp trên địa bàn Hà Nội, Ban giám hiệu & Phụ huynh các trường học (Bếp ăn học đường - BAHD), và các Cơ quan Quản lý Nhà nước (Sở Công Thương, Sở NN&PTNT, Sở Y tế, UBND Phường/Xã) với phân quyền theo cây đơn vị hành chính (DVHCVN / CO_QUAN_NN).

---

2. Sơ đồ Kiến trúc Tổng thể (High-Level System Architecture)

Rendering diagram...

---

3. Technology Stack

3.1. Frontend (apps/frontend)

• Framework: Next.js 16.1.1 (App Router, output: 'standalone'), React 19.2.3, TypeScript 5.x.
• UI & Styling: HeroUI (@heroui/react 2.8.7), Tailwind CSS 4.x, Lucide Icons (lucide-react), Framer Motion.
• Form & Data Fetching: react-hook-form 7.71 + zod 4.3, axios, swr.
• Maps, Charts & Media: Leaflet (leaflet, react-leaflet cho bản đồ vùng nguyên liệu và lộ trình vận chuyển), Recharts (recharts), QRCode (qrcode, html5-qrcode), PDF/Canvas Export (jspdf, html2canvas).

3.2. Core Backend (apps/backend), Zalo Backend (apps/zalo-be) & Integration Gateway (apps/integration-gateway)

• Framework: NestJS 11.x trên nền Express 5.x và Node.js >=20.
• ORM & Database: Prisma 6.19.2 kết nối PostgreSQL 16 (hỗ trợ immutable_unaccent, JSONB, Transactional Advisory Lock pg_advisory_xact_lock, và Trigger bảo vệ Immutable Ledger sgtin_movements).
• Job Queue & Async Processing: BullMQ (bullmq + @nestjs/bullmq) trên Redis 7, giám sát qua Bull Board (@bull-board/api, @bull-board/express).
• Cryptography & Digital Signatures:
  • Ed25519 (node:crypto + worker pool piscina) để ký W3C Verifiable Credentials cho từng mã SGTIN và verify webhook từ Spores Blockchain.
  • AES-256-GCM (@gotrace/integration-crypto + src/common/helpers/cryto.ts) cho Envelope Encryption bảo vệ DID private key của doanh nghiệp và credentials tích hợp.
  • HMAC-SHA256 để xác thực internal service-to-service và webhook Zalo OA.
• File Processing & Object Storage: ExcelJS (exceljs cho Unified Import/Export Engine TXNG-F49), MinIO SDK (minio) và AWS SDK S3 v3 (@aws-sdk/client-s3).

---

4. Bốn Trụ cột Nghiệp vụ (4 Business Pillars)

1. Core Traceability (TXNG & Đa ngành F41): Quản lý trọn vẹn vòng đời sản phẩm từ Input Sources đa ngành (VSIC 2025 / GS1 GPC Brick) → Raw Material Zones / Facilities → Products (GTIN) → Production Plans & Production Logs → Batches → Stamp Print Plans & SGTIN Issuance → Multi-level Packaging (SSCC) & Combo Assembly → Warehouses & Stock Transfers → Purchase Orders (PO) & Cross-Enterprise Shipments → POS Sales & Cascading Recall (F32).
2. Bếp ăn Học đường & Nutrition (BAHD): Giải pháp chuyên biệt cho trường học và đơn vị cung cấp suất ăn: Hồ sơ bếp ăn (SchoolCafeteria) → Bảng thành phần thực phẩm (FAO/VDD) & Chuẩn RDA (RdaStandard) → Thực đơn tuần & Công thức món ăn (MenuPlan, MenuRecipe) → Nutrition Engine (NutritionBalanceService) → Lệnh chế biến & Dự trù nguyên liệu (MealProcessingOrder, IngredientDemand) → Định mức chi phí, Bảng tính giá suất ăn & Finance Ledger (FinanceLedger, CostReconciliation) → Công khai chi phí & Parent Portal (ParentPortal, MenuQrCode, ParentFeedback).
3. Quản lý Nhà nước & ATTP Oversight (QLNN): Bộ công cụ điều hành và giám sát cho các Sở/Ngành và UBND Phường/Xã: Executive Dashboard (OLAP Cube KPI) → Cross-Enterprise Dashboard & Cafeteria Oversight → Kế hoạch thanh kiểm tra (OversightPlan) → Biên bản kiểm tra thực địa (OversightInspection) → Quản lý vi phạm & Hậu kiểm khắc phục (OversightViolation, OversightRemediation) → Alert Rule Engine (Alerts & ThresholdEvents) → Quản lý Chợ/Điểm kinh doanh (TradingVenue) & Cán bộ thanh tra (Personnel).
4. Zalo MiniApp (zalo-be) & Integration Gateway (integration-gateway): Mở rộng tương tác hiện trường qua Zalo MiniApp cho Driver (nhận/giao chuyến hàng, ký biên bản điện tử), Enterprise (tạo/nhận lô hàng nhanh), và Consumer (quét QR xác nhận mua hàng); đồng thời đồng bộ bất đồng bộ theo mẫu Transactional Outbox tới 12 cổng dữ liệu quốc gia và bộ ngành.