577 lines
24 KiB
Markdown
577 lines
24 KiB
Markdown
# LCBP3-DMS Architecture Documentation
|
|
|
|
---
|
|
|
|
**title:** 'LCBP3-DMS Architecture Documentation'
|
|
**version:** 1.9.8
|
|
**status:** active
|
|
**owner:** Nattanin Peancharoen
|
|
**last_updated:** 2026-05-30
|
|
**related:**
|
|
|
|
- specs/02-Architecture/02-01-system-context.md
|
|
- specs/02-Architecture/02-02-software-architecture.md
|
|
- specs/02-Architecture/02-03-network-design.md
|
|
- specs/02-Architecture/02-04-api-design.md
|
|
- specs/06-Decision-Records/
|
|
|
|
---
|
|
|
|
## 📋 Table of Contents
|
|
|
|
1. [System Context & Architecture](#1-system-context--architecture)
|
|
2. [Software Architecture & Design](#2-software-architecture--design)
|
|
3. [Network Design & Security](#3-network-design--security)
|
|
4. [API Design & Error Handling](#4-api-design--error-handling)
|
|
5. [AI Architecture (ADR-023/023A/024/025)](#5-ai-architecture-adr-023023a)
|
|
6. [Architecture Decision Records (ADRs)](#6-architecture-decision-records-adrs)
|
|
|
|
---
|
|
|
|
## 1. System Context & Architecture
|
|
|
|
### 1.1 System Overview
|
|
|
|
ระบบ LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) ถูกออกแบบด้วยสถาปัตยกรรมแบบ **Headless/API-First Architecture** โดยทำงานแบบ **On-Premise 100%** บนเครื่องเซอร์ฟเวอร์ QNAP และ ASUSTOR
|
|
|
|
### 1.2 Architecture Principles
|
|
|
|
1. **Data Integrity First:** ความถูกต้องของข้อมูลต้องมาก่อนทุกอย่าง
|
|
2. **Security by Design & Container Isolation:** รักษาความปลอดภัยที่ทุกชั้น และแยกส่วนการทำงานของแต่ละระบบอย่างชัดเจน
|
|
3. **On-Premise First:** ข้อมูลและระบบงานทั้งหมดต้องอยู่ภายในเครือข่ายของโครงการเท่านั้น
|
|
4. **Resilience:** ทนทานต่อ Failure และ Recovery ได้รวดเร็ว
|
|
5. **Observability:** ติดตามและวิเคราะห์สถานะระบบได้ง่าย
|
|
|
|
### 1.3 Hardware Infrastructure
|
|
|
|
| Component | Specification | Role | IP Address |
|
|
| --------------------- | ----------------------------------------- | ----------------------------------- | ------------ |
|
|
| **Primary Server** | QNAP TS-473A (AMD Ryzen V1500B, 32GB RAM) | Primary NAS for DMS, Container Host | 192.168.10.8 |
|
|
| **Backup Server** | ASUSTOR AS5304T | Backup / Secondary NAS | 192.168.10.9 |
|
|
| **Network Interface** | LACP bonding (IEEE 802.3ad) | High availability & bandwidth | - |
|
|
|
|
### 1.4 Container Isolation & Environment
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph PublicZone["🌐 PUBLIC ZONE"]
|
|
NPM["NPM (Reverse Proxy)<br/>Ports: 80, 443"]
|
|
end
|
|
|
|
subgraph AppZone["📱 APPLICATION ZONE (Docker Network 'lcbp3')"]
|
|
Frontend["Next.js"]
|
|
Backend["NestJS"]
|
|
N8N["n8n"]
|
|
Gitea["Gitea"]
|
|
end
|
|
|
|
subgraph DataZone["💾 DATA ZONE (Internal Only)"]
|
|
MariaDB["MariaDB"]
|
|
Redis["Redis"]
|
|
ES["Elasticsearch"]
|
|
end
|
|
|
|
PublicZone -->|HTTPS Only| AppZone
|
|
AppZone -->|Internal API| DataZone
|
|
```
|
|
|
|
### 1.5 Core Services Architecture
|
|
|
|
| Service | Application Name | Domain | Technology | Purpose |
|
|
| ------------ | ---------------- | ------------------- | ------------------- | ------------------ |
|
|
| **Frontend** | lcbp3-frontend | lcbp3.np-dms.work | Next.js 16.2.0 | Web UI |
|
|
| **Backend** | lcbp3-backend | backend.np-dms.work | NestJS 11 | API Server & Logic |
|
|
| **Database** | lcbp3-db | db.np-dms.work | MariaDB 11.8 | Primary Data |
|
|
| **Proxy** | lcbp3-npm | npm.np-dms.work | Nginx Proxy Mgr | Gateway & SSL |
|
|
| **Workflow** | lcbp3-n8n | n8n.np-dms.work | n8n | Process Automation |
|
|
| **Git** | git | git.np-dms.work | Gitea | Code Repository |
|
|
| **Cache** | - | - | Redis | Caching, Locking |
|
|
| **Search** | - | - | Elasticsearch 9.3.4 | Full-text Indexing |
|
|
|
|
### 1.6 Data Flow & Interactions
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant NPM as Nginx Proxy
|
|
participant BE as Backend (NestJS)
|
|
participant Redis as Redis Cache
|
|
participant DB as MariaDB
|
|
|
|
Client->>NPM: HTTP Request + JWT
|
|
NPM->>BE: Forward Request
|
|
|
|
BE->>BE: Rate Limit Check & Validate Input
|
|
BE->>Redis: Get User Permissions (RBAC Cache)
|
|
Redis-->>BE: Permission Data
|
|
BE->>BE: Verify Permission
|
|
|
|
BE->>DB: Process Logic & Save
|
|
BE->>Redis: Invalidate affected Cache
|
|
|
|
BE-->>Client: JSON Response
|
|
```
|
|
|
|
### 1.7 Backup & Disaster Recovery
|
|
|
|
- **Database Backup:** ทำ Automated Backup รายวันด้วย QNAP HBS 3
|
|
- **File Backup:** ทำ Snapshot จาก `/share/dms-data` บน QNAP ไปยัง ASUSTOR
|
|
- **Recovery Standard:** หาก NAS พัง สามารถ Restore Config และรัน `docker-compose up` ขึ้นใหม่ได้ทันที
|
|
|
|
---
|
|
|
|
## 2. Software Architecture & Design
|
|
|
|
### 2.1 Backend Module Architecture (NestJS)
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Core Modules"
|
|
Common[CommonModule<br/>Shared Services]
|
|
Auth[AuthModule<br/>JWT & Guards]
|
|
User[UserModule<br/>User Management]
|
|
end
|
|
|
|
subgraph "Business Modules"
|
|
Project[ProjectModule<br/>Projects & Contracts]
|
|
Corr[CorrespondenceModule<br/>Correspondences]
|
|
RFA[RfaModule<br/>RFA Management]
|
|
Drawing[DrawingModule<br/>Shop & Contract Drawings]
|
|
Circ[CirculationModule<br/>Circulation Sheets]
|
|
end
|
|
|
|
subgraph "Supporting Modules"
|
|
Workflow[WorkflowEngineModule<br/>Unified Workflow]
|
|
Numbering[DocumentNumberingModule<br/>Auto Numbering]
|
|
Search[SearchModule<br/>Elasticsearch]
|
|
end
|
|
|
|
Corr --> Workflow
|
|
RFA --> Workflow
|
|
Circ --> Workflow
|
|
|
|
Corr --> Numbering
|
|
RFA --> Numbering
|
|
|
|
Search --> Corr
|
|
Search --> RFA
|
|
Search --> Drawing
|
|
```
|
|
|
|
### 2.2 Key Architectural Patterns
|
|
|
|
#### Unified Workflow Engine (DSL-Based)
|
|
|
|
ระบบการเดินเอกสารใช้ Engine กลางเดียวกัน ผ่าน **Workflow DSL (JSON Configuration)**
|
|
|
|
- **Separation of Concerns:** Modules เก็บเฉพาะข้อมูล (Data) ส่วน Flow/State ถูกจัดการโดย Engine
|
|
- **Versioning:** อาศัย Workflow Definition Version ป้องกันความขัดแย้งของ State
|
|
|
|
#### Double-Locking Mechanism (Auto Numbering)
|
|
|
|
เพื่อป้องกัน Race Condition ในการขอเลขเอกสารพร้อมกัน:
|
|
|
|
- **Layer 1:** Redis Distributed Lock (ล็อคการเข้าถึงในระดับ Server/Network)
|
|
- **Layer 2:** Optimistic Database Lock ผ่าน `@VersionColumn()` (ป้องกันระดับ Data Record)
|
|
|
|
#### Idempotency
|
|
|
|
ทุก API ที่แก้ไขสถานะจะต้องส่ง `Idempotency-Key` ป้องกันผู้ใช้กดยืนยันซ้ำสองรอบ
|
|
|
|
### 2.3 File Upload Flow (Two-Phase Storage)
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant BE as Backend
|
|
participant Temp as Temp Storage
|
|
participant Virus as ClamAV
|
|
participant Perm as Permanent Storage
|
|
|
|
Client->>BE: Upload File
|
|
BE->>Virus: Scan File
|
|
Virus-->>BE: Clean
|
|
BE->>Temp: Save to temp/
|
|
BE-->>Client: Return temp_id
|
|
|
|
Client->>BE: Create Document (with temp_id)
|
|
BE->>BE: Validate & Save to DB
|
|
BE->>Perm: Move temp/ → permanent/
|
|
BE->>Temp: Cleanup temp file
|
|
BE-->>Client: Success
|
|
```
|
|
|
|
### 2.4 Security Architecture
|
|
|
|
#### Rate Limiting (Redis-backed)
|
|
|
|
| Endpoint Type | Limit | Scope |
|
|
| ---------------- | ------------- | ----- |
|
|
| Anonymous | 100 req/hour | IP |
|
|
| File Upload | 50 req/hour | User |
|
|
| Document Control | 2000 req/hour | User |
|
|
| Admin | 5000 req/hour | User |
|
|
|
|
#### Authorization checking flow (CASL)
|
|
|
|
1. ดึง JWT Token ตรวจสอบความถูกต้อง
|
|
2. โหลด User Permissions จาก Redis
|
|
3. ตรวจสอบเงื่อนไขตาม Context (Global, Organization, Project, Contract)
|
|
4. พิจารณาอนุญาตหากระดับใดระดับหนึ่งอนุญาต
|
|
|
|
### 2.5 Resilience & Error Handling
|
|
|
|
- **Circuit Breaker:** ใช้งานครอบ API ภายนอก (Email, LINE Notify)
|
|
- **Retry Mechanism:** สำหรับกระบวนการสำคัญชั่วคราว
|
|
- **Graceful Degradation:** หาก Search Engine ล่ม ระบบสลับไปใช้ Database Query พื้นฐานชั่วคราวได้
|
|
|
|
---
|
|
|
|
## 3. Network Design & Security
|
|
|
|
### 3.1 Network Segmentation (VLANs)
|
|
|
|
| VLAN ID | Name | Purpose | Subnet | Gateway | Notes |
|
|
| ------- | ------ | ------------------ | --------------- | ------------ | ----------------------------------------- |
|
|
| 10 | SERVER | Server & Storage | 192.168.10.0/24 | 192.168.10.1 | Servers (QNAP, ASUSTOR). Static IPs ONLY. |
|
|
| 20 | MGMT | Management & Admin | 192.168.20.0/24 | 192.168.20.1 | Network devices, Admin PC. |
|
|
| 30 | USER | User Devices | 192.168.30.0/24 | 192.168.30.1 | Staff PC, Printers. |
|
|
| 40 | CCTV | Surveillance | 192.168.40.0/24 | 192.168.40.1 | Cameras, NVR. Isolated. |
|
|
| 50 | VOICE | IP Phones | 192.168.50.0/24 | 192.168.50.1 | SIP traffic. Isolated. |
|
|
| 60 | DMZ | Public Services | 192.168.60.0/24 | 192.168.60.1 | DMZ. Isolated from Internal. |
|
|
| 70 | GUEST | Guest Wi-Fi | 192.168.70.0/24 | 192.168.70.1 | Isolated Internet Access only. |
|
|
|
|
### 3.2 Security Zones
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph PublicZone["🌐 PUBLIC ZONE"]
|
|
NPM["NPM (Reverse Proxy)<br/>Ports: 80, 443"]
|
|
end
|
|
|
|
subgraph AppZone["📱 APPLICATION ZONE (Docker Network 'lcbp3')"]
|
|
Frontend["Next.js"]
|
|
Backend["NestJS"]
|
|
N8N["n8n"]
|
|
Gitea["Gitea"]
|
|
end
|
|
|
|
subgraph DataZone["💾 DATA ZONE (QNAP - Internal Only)"]
|
|
MariaDB["MariaDB"]
|
|
Redis["Redis"]
|
|
ES["Elasticsearch"]
|
|
end
|
|
|
|
subgraph InfraZone["🛠️ INFRASTRUCTURE ZONE (ASUSTOR)"]
|
|
Backup["Backup Services"]
|
|
Registry["Docker Registry"]
|
|
Monitoring["Prometheus + Grafana"]
|
|
end
|
|
|
|
PublicZone -->|HTTPS Only| AppZone
|
|
AppZone -->|Internal API| DataZone
|
|
DataZone -.->|Backup| InfraZone
|
|
AppZone -.->|Metrics| InfraZone
|
|
```
|
|
|
|
### 3.3 Network Topology
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Internet
|
|
WAN[("Internet<br/>WAN")]
|
|
end
|
|
|
|
subgraph Router["ER7206 Router"]
|
|
R[("ER7206<br/>192.168.20.1")]
|
|
end
|
|
|
|
subgraph CoreSwitch["SG3210X-M2 Core Switch"]
|
|
CS[("SG3210X-M2<br/>192.168.20.4")]
|
|
end
|
|
|
|
subgraph Servers["VLAN 10 - Servers"]
|
|
QNAP[(" QNAP<br/>192.168.10.8")]
|
|
ASUSTOR[(" ASUSTOR<br/>192.168.10.9")]
|
|
end
|
|
|
|
WAN -->|Port 2| R
|
|
R -->|SFP Port 1| CS
|
|
CS -->|Port 3-4 LACP| QNAP
|
|
CS -->|Port 5-6 LACP| ASUSTOR
|
|
```
|
|
|
|
### 3.4 Firewall Rules (ACLs)
|
|
|
|
กฎของ Firewall จะถูกกำหนดตามหลักการอนุญาตแค่สิ่งที่ต้องการ (Default Deny)
|
|
|
|
| Priority | Rule | Policy | Source | Destination | Ports |
|
|
| -------- | ---------------------- | ------ | ----------------- | ----------------- | -------------------- |
|
|
| 1 | Allow-User-DHCP | Allow | Network → VLAN 30 | IP → 192.168.30.1 | DHCP |
|
|
| 2 | Allow-Guest-DHCP | Allow | Network → VLAN 70 | IP → 192.168.70.1 | DHCP |
|
|
| 3 | Isolate-Servers | Deny | Network → VLAN 10 | Network → VLAN 30 | All |
|
|
| 4 | Block-User-to-Mgmt | Deny | Network → VLAN 30 | Network → VLAN 20 | All |
|
|
| 5 | Allow-User-to-Services | Allow | Network → VLAN 30 | IP → QNAP | Web (443,8443,80,81) |
|
|
| 100 | Default | Deny | Any | Any | All |
|
|
|
|
### 3.5 QoS (Quality of Service) Settings
|
|
|
|
| Priority | DSCP Value | Traffic Type | Application |
|
|
| ----------- | ---------- | --------------------- | ---------------------- |
|
|
| Highest (7) | EF (46) | Voice (SIP/RTP) | IP Phones (VLAN 50) |
|
|
| High (6) | AF41 (34) | Video Surveillance | CCTV Cameras (VLAN 40) |
|
|
| Medium (5) | AF31 (26) | Critical Applications | DMS Backend, Database |
|
|
| Low (4) | AF21 (18) | Best Effort | Web browsing, Email |
|
|
|
|
---
|
|
|
|
## 4. API Design & Error Handling
|
|
|
|
### 4.1 API Design Principles
|
|
|
|
#### API-First Approach
|
|
|
|
- **ออกแบบ API ก่อนการ Implement:** ทำการออกแบบ API Endpoint และ Data Contract ให้ชัดเจนก่อนเริ่มเขียนโค้ด
|
|
- **Documentation-Driven:** ใช้ OpenAPI/Swagger เป็นเอกสารอ้างอิงหลัก
|
|
- **Contract Testing:** ทดสอบ API ตาม Contract ที่กำหนดไว้
|
|
|
|
#### RESTful Principles
|
|
|
|
- ใช้ HTTP Methods อย่างถูกต้อง: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
|
|
- ใช้ HTTP Status Codes ที่เหมาะสม
|
|
- Resource-Based URL Design
|
|
- Stateless Communication
|
|
|
|
### 4.2 Authentication & Authorization
|
|
|
|
#### JWT-Based Authentication
|
|
|
|
- **Token Management:**
|
|
- Access Token Expiration: 8 ชั่วโมง
|
|
- Refresh Token Expiration: 7 วัน
|
|
- Token Rotation: รองรับการหมุนเวียน Refresh Token
|
|
|
|
#### Authorization (RBAC) (CASL)
|
|
|
|
ใช้ระบบ 4-Level Permission Hierarchy (Global, Organization, Project, Contract)
|
|
|
|
```typescript
|
|
@RequirePermission('correspondence.create')
|
|
@Post('correspondences')
|
|
async createCorrespondence(@Body() dto: CreateCorrespondenceDto) {
|
|
// Implementation
|
|
}
|
|
```
|
|
|
|
### 4.3 API Conventions
|
|
|
|
#### Base URL Structure
|
|
|
|
```
|
|
https://backend.np-dms.work/api/v1/{resource}
|
|
```
|
|
|
|
#### HTTP Methods & Usage
|
|
|
|
| Method | Usage | Idempotent | Example |
|
|
| -------- | ------------------------------ | ---------- | -------------------------------------- |
|
|
| `GET` | ดึงข้อมูล (Read) | ✅ Yes | `GET /api/v1/correspondences` |
|
|
| `POST` | สร้างข้อมูลใหม่ (Create) | ❌ No\* | `POST /api/v1/correspondences` |
|
|
| `PUT` | อัปเดตทั้งหมด (Full Update) | ✅ Yes | `PUT /api/v1/correspondences/:uuid` |
|
|
| `PATCH` | อัปเดตบางส่วน (Partial Update) | ✅ Yes | `PATCH /api/v1/correspondences/:uuid` |
|
|
| `DELETE` | ลบข้อมูล (Soft Delete) | ✅ Yes | `DELETE /api/v1/correspondences/:uuid` |
|
|
|
|
### 4.4 Request Format
|
|
|
|
**Request Headers:**
|
|
|
|
```http
|
|
Content-Type: application/json
|
|
Authorization: Bearer <access_token>
|
|
Idempotency-Key: <uuid> # สำหรับ POST/PUT/DELETE
|
|
```
|
|
|
|
### 4.5 Response Formats
|
|
|
|
#### Success Response
|
|
|
|
```typescript
|
|
{
|
|
"data": {
|
|
"uuid": "019505a1-7c3e-7000-8000-abc123def456",
|
|
"document_number": "CORR-2024-0001",
|
|
"subject": "...",
|
|
},
|
|
"meta": {
|
|
"timestamp": "2024-01-01T00:00:00Z",
|
|
"version": "1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Error Response Format
|
|
|
|
```typescript
|
|
{
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Validation failed on input data",
|
|
"statusCode": 400,
|
|
"timestamp": "2024-01-01T00:00:00Z",
|
|
"path": "/api/correspondences",
|
|
"details": [
|
|
{
|
|
"field": "subject",
|
|
"message": "Subject is required",
|
|
"value": null
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.6 Error Handling Strategy
|
|
|
|
#### Global Exception Filter
|
|
|
|
คลาสจัดการ Error หลักที่จะจับและดัดแปลง Error ส่งคืน Client อย่างสม่ำเสมอ
|
|
|
|
#### Custom Business Exception
|
|
|
|
สำหรับจัดการข้อผิดพลาดเชิงความสัมพันธ์ หรือเงื่อนไขธุรกิจ
|
|
|
|
```typescript
|
|
throw new BusinessException('Cannot approve correspondence in current status', 'INVALID_WORKFLOW_TRANSITION');
|
|
```
|
|
|
|
### 4.7 API Security & Rate Limiting
|
|
|
|
#### File Upload Security
|
|
|
|
- **Virus Scanning:** ใช้ ClamAV scan ทุกไฟล์
|
|
- **File Type Validation:** White-list (PDF, DWG, DOCX, XLSX, ZIP)
|
|
- **File Size Limit:** 50MB per file
|
|
- **Two-Phase Storage:** Upload to `temp/` → Commit to `permanent/`
|
|
|
|
---
|
|
|
|
## 5. AI Architecture (ADR-023/023A/024/025)
|
|
|
|
### 5.1 AI Integration Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Frontend"
|
|
UI["Document Review Form"]
|
|
end
|
|
|
|
subgraph "Backend (NestJS)"
|
|
Gateway["AI Gateway API"]
|
|
Queue["BullMQ Queues"]
|
|
Validation["Human Validation"]
|
|
end
|
|
|
|
subgraph "Admin Desktop (Desk-5439)"
|
|
Ollama["Ollama Engine<br/>gemma4:e4b Q8_0 + nomic-embed-text"]
|
|
OCR["PaddleOCR + PyThaiNLP"]
|
|
end
|
|
|
|
subgraph "Vector Database"
|
|
Qdrant["Qdrant<br/>Project-scoped Embeddings"]
|
|
end
|
|
|
|
UI --> Gateway
|
|
Gateway --> Queue
|
|
Queue --> Ollama
|
|
Ollama --> Validation
|
|
Validation --> Gateway
|
|
Gateway --> Qdrant
|
|
```
|
|
|
|
### 5.2 Key Components
|
|
|
|
| Component | Location | Purpose |
|
|
| ----------------- | ------------------------- | ------------------------------------------------------- |
|
|
| **AI Gateway** | Backend (NestJS) | API endpoints, validation, audit logging |
|
|
| **BullMQ Queues** | Backend (NestJS) | ai-realtime (RAG/Suggest), ai-batch (OCR/Extract/Embed) |
|
|
| **Ollama Engine** | Admin Desktop (Desk-5439) | gemma4:e4b Q8_0 (LLM) + nomic-embed-text (Embedding) |
|
|
| **OCR Engine** | Admin Desktop (Desk-5439) | PaddleOCR + PyThaiNLP (Thai/English text extraction) |
|
|
| **Qdrant** | QNAP NAS | Vector storage with project isolation |
|
|
|
|
### 5.3 AI Architecture Rules
|
|
|
|
- **AI Isolation:** All AI processing on Admin Desktop only (Desk-5439)
|
|
- **Data Privacy:** No cloud AI services, on-premises only
|
|
- **Audit Trail:** Log all AI interactions and human validations
|
|
- **Rate Limiting:** Prevent AI abuse and resource exhaustion
|
|
- **Validation:** All AI outputs must be validated before use
|
|
- **Multi-tenant Isolation:** Qdrant queries MUST include projectPublicId filter
|
|
|
|
### 5.4 2-Model Stack (ADR-023A)
|
|
|
|
- **gemma4:e4b Q8_0** (~4.0GB VRAM) - Main LLM for classification, tagging, extraction
|
|
- **nomic-embed-text** (~0.3GB VRAM) - Text embedding for RAG
|
|
- **Total VRAM Peak:** ~4.3GB
|
|
|
|
---
|
|
|
|
## 6. Architecture Decision Records (ADRs)
|
|
|
|
### 6.1 Key ADRs Implemented
|
|
|
|
| ADR | Title | Status | Description |
|
|
| ------------ | ------------------------------- | --------- | -------------------------------------------------------------------------------------- |
|
|
| **ADR-001** | Unified Workflow Engine | ✅ Active | DSL-based workflow implementation |
|
|
| **ADR-002** | Document Numbering Strategy | ✅ Active | Document number generation + locking |
|
|
| **ADR-007** | Error Handling Strategy | ✅ Active | Layered error classification |
|
|
| **ADR-008** | Email Notification Strategy | ✅ Active | BullMQ + multi-channel notification |
|
|
| **ADR-009** | Database Migration Strategy | ✅ Active | Schema changes — edit SQL directly |
|
|
| **ADR-016** | Security Authentication | ✅ Active | Auth, RBAC, file upload security |
|
|
| **ADR-019** | Hybrid Identifier Strategy | ✅ Active | INT PK + UUIDv7 Public API |
|
|
| **ADR-021** | Workflow Context | ✅ Active | Integrated workflow & step attachments |
|
|
| **ADR-023** | Unified AI Architecture | ✅ Active | AI boundaries and pipeline |
|
|
| **ADR-023A** | AI Model Revision | ✅ Active | 2-Model stack with BullMQ queues |
|
|
| **ADR-024** | Intent Classification Strategy | ✅ Active | Hybrid Pattern → LLM Fallback intent routing |
|
|
| **ADR-025** | AI Tool Layer Architecture | ✅ Active | Server-side Tool dispatch, CASL-guarded bridge |
|
|
| **ADR-026** | Document Chat UI Pattern | ✅ Active | Side-panel document chat UI |
|
|
| **ADR-027** | AI Admin Console & Dynamic Ctrl | ✅ Active | AI Admin Panel + dynamic model/prompt control |
|
|
| **ADR-028** | Migration Architecture Refactor | ✅ Active | Staging Queue & post-migration cleanup |
|
|
| **ADR-029** | Dynamic Prompt Management | ✅ Active | Prompt templates in DB (`ai_prompts`), Redis cache TTL 60s, versioned |
|
|
| **ADR-031** | Hermes Agent & Telegram Bridge | 📝 Draft | Optional DevOps Agent with Telegram commands, read-only diagnostics |
|
|
| **ADR-032** | Typhoon OCR Integration | 📝 Draft | Typhoon OCR-3B + typhoon2.1-gemma3-4b on Admin Desktop, VRAM monitoring, Redis caching |
|
|
|
|
### 6.2 ADR References
|
|
|
|
For detailed architectural decisions, please refer to:
|
|
|
|
- `specs/06-Decision-Records/` - Complete ADR documentation
|
|
- `AGENTS.md` - Quick-reference rules and enforcement
|
|
|
|
---
|
|
|
|
## 📚 Related Documentation
|
|
|
|
- **System Context:** `specs/02-Architecture/02-01-system-context.md`
|
|
- **Software Architecture:** `specs/02-Architecture/02-02-software-architecture.md`
|
|
- **Network Design:** `specs/02-Architecture/02-03-network-design.md`
|
|
- **API Design:** `specs/02-Architecture/02-04-api-design.md`
|
|
- **Decision Records:** `specs/06-Decision-Records/`
|
|
- **Data Schema:** `specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-*.sql`
|
|
- **Engineering Guidelines:** `specs/05-Engineering-Guidelines/`
|
|
|
|
---
|
|
|
|
## 🔄 Version History
|
|
|
|
| Version | Date | Changes |
|
|
| --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **1.9.7** | 2026-05-25 | Added ADR-029 Dynamic Prompt Management to ADR table; bumped version/date |
|
|
| **1.9.5** | 2026-05-22 | Added ADR-024/025/026/027/028 to ADR reference table; updated AI Architecture section heading; schema reference corrected to v1.9.0 |
|
|
| **1.9.2** | 2026-05-18 | Complete restructure following specs/02-Architecture format, added comprehensive diagrams, updated AI Architecture (ADR-023/023A) |
|
|
| **1.9.0** | 2026-05-13 | AI Architecture consolidation, Agent Infrastructure standardization |
|
|
| **1.8.0** | 2026-02-23 | Initial architecture documentation |
|
|
|
|
---
|
|
|
|
_This document is maintained as part of the LCBP3-DMS project specification suite._
|