Kiến trúc hệ thống

Cấu trúc Monorepo

SmartCK Hub sử dụng pnpm workspace kết hợp Turborepo để quản lý monorepo:

smartck-hub/
├── apps/
│   ├── backend/          # NestJS 10 - REST API
│   ├── frontend/         # React 19 + Vite 7
│   └── docs/             # Docusaurus - tài liệu
├── packages/
│   ├── api-client/       # Orval auto-generated API hooks
│   ├── shared-types/     # TypeScript types dùng chung
│   ├── eslint-config/    # ESLint shared config
│   └── tsconfig/         # TypeScript shared config
├── scripts/              # Dev scripts, Playwright helpers
├── turbo.json            # Turborepo pipeline config
└── pnpm-workspace.yaml   # Workspace definition

Backend - Modular Monolith

Backend được thiết kế theo pattern Modular Monolith -- không phải microservices, nhưng code được tổ chức thành các module độc lập với ranh giới rõ ràng.

Tầng kiến trúc

src/
├── main.ts                    # Entry point
├── app.module.ts              # Root module
├── modules/                   # Business modules
│   ├── iam/                   # Identity & Access Management
│   ├── commercial/            # Kinh doanh
│   ├── delivery/              # Vận hành
│   ├── finance-ops/           # Tài chính
│   └── organization/          # Tổ chức
├── infrastructure/            # Hạ tầng kỹ thuật
│   ├── cache/                 # Redis service
│   ├── config/                # App configuration
│   ├── database/              # Prisma service
│   ├── logger/                # Winston logger
│   ├── monitoring/            # Health check
│   └── websocket/             # Socket.IO + Redis adapter
└── shared/                    # Code dùng chung
    ├── common/                # Utils, decorators, interceptors
    ├── constants/             # Permissions, enums
    ├── filters/               # Exception filters
    ├── middleware/             # HTTP middleware
    ├── storage/               # S3 storage service
    └── validation/            # Validation service

Cấu trúc một module

Mỗi domain trong module tuân theo pattern nhất quán:

modules/commercial/
├── commercial.module.ts          # Module gốc
├── customers/
│   ├── controllers/              # HTTP endpoints
│   ├── services/                 # Business logic
│   ├── repositories/             # Data access (Prisma)
│   ├── dto/                      # Request/Response DTOs
│   └── customers.module.ts       # Sub-module
├── contracts/
│   └── ...
└── service-packages/
    └── ...

Nguyên tắc

• Controller: Chỉ xử lý HTTP request/response, validate input
• Service: Chứa business logic, gọi repository
• Repository: Truy vấn database qua Prisma, không chứa logic
• DTO: Định nghĩa shape dữ liệu vào/ra với class-validator

Frontend - Feature-based Architecture

Cấu trúc thư mục

src/
├── features/                     # File-based routing (TanStack Router)
│   ├── __root.tsx                # Root layout
│   ├── (authenticated)/          # Route group yêu cầu đăng nhập
│   │   ├── admin/                # Quản trị
│   │   ├── business/             # Kinh doanh
│   │   ├── operations/           # Vận hành
│   │   ├── organization/         # Tổ chức
│   │   └── overview/             # Dashboard
│   ├── (authentication)/         # Đăng nhập, quên mật khẩu
│   └── (errors)/                 # Trang lỗi 404, 500
├── components/
│   ├── ui/                       # 30 Radix UI components
│   ├── shared/                   # empty-state, error-boundary, loading
│   └── layouts/                  # Layout components
├── hooks/                        # Custom hooks
├── stores/                       # Zustand stores
├── layouts/                      # classic-sidebar, empty
├── services/                     # API service layer
└── lib/                          # Utilities

Quản lý State

Loại state	Công cụ	Ví dụ
Server	TanStack Query	Danh sách dự án, chi tiết hợp đồng
Client	Zustand	Auth state, notification state
Form	React Hook Form	Form tạo khách hàng, form login
URL	TanStack Router	Filters, pagination, search params

Luồng dữ liệu (Data Flow)

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │     │   Backend    │     │  PostgreSQL  │
│  React 19    │────▶│  NestJS 10   │────▶│  Multi-schema│
│  + Vite 7    │◀────│  + Prisma 6  │◀────│  5 schemas   │
└──────┬───────┘     └──────┬───────┘     └──────────────┘
       │                    │
       │  Auto-generated    │  Cache layer
       │  API hooks         │
       ▼                    ▼
┌──────────────┐     ┌──────────────┐
│  Orval       │     │    Redis     │
│  api-client  │     │  Cache/Queue │
└──────────────┘     └──────────────┘

Quy trình tạo API contract:

1. Backend định nghĩa endpoint + DTO (NestJS decorators)
2. Swagger tự động generate OpenAPI spec tại /api/docs-json
3. Orval đọc spec, sinh ra typed React Query hooks vào packages/api-client
4. Frontend import hooks, gọi API với full type-safety

# Regenerate API client khi backend thay đổi
pnpm api:generate

Realtime Communication

WebSocket được thiết kế với Socket.IO + Redis adapter để hỗ trợ scaling:

• Notifications: Thông báo realtime đến user cụ thể
• Cache invalidation: Khi admin thay đổi config, frontend tự cập nhật

Tổng quan công nghệ

Tầng	Công nghệ
Frontend	React 19, Vite 7, TanStack Router, TanStack Query
UI	Radix UI, Tailwind CSS 4, React Hook Form + Zod
Backend	NestJS 10, Prisma 6.9, class-validator
Database	PostgreSQL (multi-schema), Redis 7
Realtime	Socket.IO + Redis adapter
Build	pnpm, Turborepo, SWC
Quality	ESLint, Prettier, jscpd, Knip, dependency-cruiser