> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econtractid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kiến trúc Hệ thống

> Tổng quan kiến trúc kỹ thuật của nền tảng econtractid

## Tổng quan kiến trúc

econtractid được xây dựng theo kiến trúc **microservices** hiện đại, đảm bảo khả năng mở rộng, bảo mật cao và tính sẵn sàng liên tục.

```
┌─────────────────────────────────────────────────────┐
│                    CLIENT LAYER                      │
│  Web App (Angular)  │  Mobile App  │  3rd-party API  │
└──────────────┬──────────────────────────────────────┘
               │ HTTPS / REST / WebSocket
┌──────────────▼──────────────────────────────────────┐
│                 API GATEWAY (NestJS)                 │
│     Auth  │  Rate Limiting  │  Load Balancing        │
└──────┬──────────────────────────────────────┬────────┘
       │                                      │
┌──────▼──────────┐                 ┌─────────▼────────┐
│  Contract       │                 │  Signing         │
│  Service        │                 │  Service         │
│  (NestJS)       │                 │  (NestJS)        │
└──────┬──────────┘                 └─────────┬────────┘
       │                                      │
┌──────▼──────────┐                 ┌─────────▼────────┐
│  PostgreSQL DB  │                 │  HSM / CA        │
│  (Hợp đồng,    │                 │  (Chứng thư số,  │
│   Người dùng)  │                 │   Private Key)   │
└─────────────────┘                 └──────────────────┘
       │
┌──────▼──────────┐
│  File Storage   │
│  (MinIO / S3)   │
└─────────────────┘
```

***

## Các thành phần chính

### Frontend – Angular SPA

* Framework: **Angular 17+**
* UI Components: **DevExtreme**
* State Management: **NgRx**
* Giao tiếp: REST API + WebSocket (cập nhật trạng thái real-time)

### Backend – NestJS API

* Framework: **NestJS** (Node.js)
* Xác thực: **JWT** (Access Token 1h + Refresh Token 7 ngày)
* Phân quyền: **RBAC** middleware
* ORM: **TypeORM** + **PostgreSQL**
* Queue: **Bull + Redis** (xử lý gửi email, ký không đồng bộ)

### Ký số – Signing Service

* Tích hợp **CA** (Viettel-CA, VNPT-CA, FPT-CA)
* Kết nối **HSM** (Hardware Security Module) qua PKCS#11
* Chuẩn chữ ký: **PAdES** (PDF), **CAdES** (CMS)
* Kiểm tra timestamp: **TSA (Timestamp Authority)**

### Lưu trữ file

* Lưu trữ file hợp đồng: **MinIO** (tương thích S3)
* CDN: các file PDF đã ký được phân phối qua CDN để tải nhanh

***

## Luồng ký số (Signing Flow)

```
Người dùng → [Web App] → POST /api/signing/initiate
                              ↓
                    [Signing Service]
                    Tạo hash của PDF
                              ↓
                    Gửi hash → HSM/Token ký
                              ↓
                    Nhận chữ ký số (signature bytes)
                              ↓
                    Nhúng chữ ký vào PDF (PAdES)
                              ↓
                    Lưu PDF đã ký vào Storage
                              ↓
                    Cập nhật trạng thái hợp đồng → DB
                              ↓
                    Thông báo bên ký tiếp theo
```

***

## Bảo mật

| Lớp                    | Biện pháp                                     |
| ---------------------- | --------------------------------------------- |
| **Truyền dữ liệu**     | TLS 1.3 / HTTPS bắt buộc                      |
| **Xác thực**           | JWT + Refresh Token rotation                  |
| **Phân quyền**         | RBAC — kiểm tra mỗi request                   |
| **Chìa khóa riêng tư** | Lưu trong HSM, **không bao giờ** rời khỏi HSM |
| **File hợp đồng**      | Mã hoá AES-256 khi lưu trữ                    |
| **Audit log**          | Ghi nhận mọi hành động có chữ ký thời gian    |