np-dms/lcbp3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
lcbp3/ARCHITECTURE.md
T
admin ae1b1f35e1
CI / CD Pipeline / build (push) Successful in 4m51s
Details
CI / CD Pipeline / deploy (push) Successful in 12m7s
Details
feat(ai): ADR-032 Typhoon OCR integration - models, processors, cache, VRAM monitor, sandbox UI
2026-05-30 22:18:51 +07:00

24 KiB
Raw Permalink Blame History

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
  2. Software Architecture & Design
  3. Network Design & Security
  4. API Design & Error Handling
  5. AI Architecture (ADR-023/023A/024/025)
  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

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

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)

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)

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

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

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)

@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:

Content-Type: application/json
Authorization: Bearer <access_token>
Idempotency-Key: <uuid> # สำหรับ POST/PUT/DELETE

4.5 Response Formats

Success Response

{
  "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

{
  "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

สำหรับจัดการข้อผิดพลาดเชิงความสัมพันธ์ หรือเงื่อนไขธุรกิจ

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

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.

Reference in New Issue View Git Blame Copy Permalink