┌─────────────────────────────────────────┐
│   Headless/API-First Architecture       │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────┐         ┌──────────┐     │
│  │ Next.js  │ ◄─────► │  NestJS  │     │
│  │ Frontend │   API   │  Backend │     │
│  └──────────┘         └────┬─────┘     │
│                            │           │
│                       ┌────▼─────┐     │
│                       │ MariaDB  │     │
│                       │  + Redis │     │
│                       └──────────┘     │
└─────────────────────────────────────────┘

📖 เอกสารสถาปัตยกรรม

1. System Architecture

สถาปัตยกรรมระบบโดยรวม

Infrastructure & Deployment (QNAP Server)
Network Architecture
Core Services (Frontend, Backend, Database, Cache, Search)
Backend Module Architecture (13 modules)
Data Flow Architecture
Security Architecture (6 layers)
Performance & Scalability
Resilience & Error Handling
Monitoring & Observability

Key Topics:

✅ Modular Design (Domain-Driven)
✅ Two-Phase File Storage
✅ Document Numbering (Double-Lock Mechanism)
✅ Unified Workflow Engine
✅ 4-Level RBAC
✅ Caching Strategy
✅ Rate Limiting

2. API Design

การออกแบบ API แบบ RESTful

API Design Principles (API-First Approach)
Authentication & Authorization (JWT + RBAC)
API Conventions (HTTP Methods, Status Codes)
Idempotency Implementation
Pagination, Filtering & Sorting
Security Features (Rate Limiting, Input Validation)
Core Module APIs (Correspondence, RFA, Drawing, etc.)
Performance Optimization
API Versioning Strategy

Key Topics:

✅ RESTful Best Practices
✅ Idempotency-Key Header
✅ Consistent Response Format
✅ Comprehensive Error Handling
✅ Rate Limiting per Role
✅ File Upload Security

3. Data Model

โครงสร้างฐานข้อมูลและ Entity Relationships

Note

เอกสารนี้อยู่ระหว่างการพัฒนา กรุณาอ้างอิง Data Dictionary สำหรับข้อมูลละเอียด

Expected Content:

Entity Relationship Diagrams (ERD)
Database Schema Design
Table Relationships
Indexing Strategy
JSON Schema Management
Virtual Columns for Performance
Partitioning Strategy

🏗️ หลักการออกแบบ (Architecture Principles)

1. Separation of Concerns

Frontend (Next.js)     Backend (NestJS)      Database (MariaDB)
      │                      │                      │
      ├─ UI/UX              ├─ Business Logic      ├─ Data Storage
      ├─ Client State       ├─ API Endpoints       ├─ Transactions
      ├─ Validation         ├─ Authorization       ├─ Constraints
      └─ User Interaction   └─ Data Processing     └─ Relationships

2. Modular Architecture

Backend Modules (Domain-Driven):

Core Modules:
├── CommonModule (Shared Services)
├── AuthModule (JWT & Guards)
└── UserModule (User Management)

Business Modules:
├── ProjectModule (Projects & Contracts)
├── CorrespondenceModule (Correspondences)
├── RfaModule (RFA Management)
├── DrawingModule (Shop & Contract Drawings)
├── CirculationModule (Circulation Sheets)
└── TransmittalModule (Transmittals)

Supporting Modules:
├── WorkflowEngineModule (Unified Workflow)
├── DocumentNumberingModule (Auto Numbering)
├── SearchModule (Elasticsearch)
├── MasterModule (Master Data)
└── JsonSchemaModule (JSON Validation)

3. Security Layers

Layer 1: Network Security (SSL/TLS, Firewall)
Layer 2: Application Security (Rate Limiting, CSRF, XSS)
Layer 3: Authentication (JWT Tokens)
Layer 4: Authorization (4-Level RBAC)
Layer 5: Data Security (Encryption, Audit Logs)
Layer 6: File Security (Virus Scanning, Access Control)

4. Data Integrity Mechanisms

Two-Phase File Storage - ป้องกัน Orphan Files
Double-Lock Document Numbering - ป้องกัน Race Condition
Optimistic Locking - Version Column สำหรับ Concurrent Updates
Transaction Management - ACID Compliance
Idempotency - ป้องกันการทำรายการซ้ำ

🛠️ Technology Stack

Frontend Stack

Component	Technology	Purpose
Framework	Next.js 14+ (App Router)	React Framework with SSR
Language	TypeScript (ESM)	Type-safe JavaScript
Styling	Tailwind CSS + PostCSS	Utility-first CSS
Components	shadcn/ui	Accessible Component Library
State Management	TanStack Query + React Hook Form	Server State + Form State
Validation	Zod	Schema Validation
Testing	Vitest + Playwright	Unit + E2E Testing

Backend Stack

Component	Technology	Purpose
Framework	NestJS (Node.js)	Enterprise Node.js Framework
Language	TypeScript (ESM)	Type-safe JavaScript
ORM	TypeORM	Object-Relational Mapping
Authentication	JWT + Passport	Token-based Auth
Authorization	CASL	Permission Management
Validation	class-validator	DTO Validation
Queue	BullMQ (Redis)	Background Jobs
Documentation	Swagger/OpenAPI	API Documentation
Testing	Jest + Supertest	Unit + Integration Testing

Infrastructure Stack

Component	Technology	Purpose
Server	QNAP TS-473A	Physical Server
Containerization	Docker + Docker Compose	Container Orchestration
Reverse Proxy	Nginx Proxy Manager	SSL/TLS + Routing
Database	MariaDB 11.8	Relational Database
Cache	Redis 7.x	Caching + Locking
Search	Elasticsearch	Full-text Search
Version Control	Gitea	Self-hosted Git
Workflow	n8n	Workflow Automation

🎯 Key Architectural Decisions

ADR-001: Unified Workflow Engine

Decision: ใช้ Workflow Engine กลางเดียวสำหรับทุกประเภทเอกสาร

Rationale:

ลดความซ้ำซ้อนของ Code
ง่ายต่อการบำรุงรักษา
รองรับการเปลี่ยนแปลง Workflow ได้ยืดหยุ่น

Implementation:

DSL-Based Configuration (JSON)
Workflow Versioning
Polymorphic Entity Relationships

Related: ADR-001

ADR-002: Document Numbering Strategy

Decision: ใช้ Application-Level Locking แทน Database Stored Procedure

Rationale:

ยืดหยุ่นกว่า (Template-Based Generator)
ง่ายต่อการ Debug และ Monitoring
รองรับ Complex Numbering Rules
Support ทุกประเภทเอกสาร (LETTER, RFA, TRANSMITTAL, etc.)

Implementation:

Layer 1: Redis Redlock (Distributed Lock)
Layer 2: Optimistic Database Lock (@VersionColumn())
Retry: Exponential Backoff with Jitter
Counter Key: Composite PK (8 columns)

Documentation:

Related: ADR-002

ADR-003: Two-Phase File Storage

Decision: แยกการอัปโหลดไฟล์เป็น 2 ขั้นตอน (Upload → Commit)

Rationale:

ป้องกัน Orphan Files
รักษา Data Integrity
รองรับ Transaction Rollback

Implementation:

Phase 1: Upload to temp/ → Return temp_id
Phase 2: Commit to permanent/ when operation succeeds
Cleanup: Cron Job ลบไฟล์ค้างใน temp/ > 24h

Related: ADR-003

ADR-004: 4-Level RBAC

Decision: ใช้ Permission Hierarchy 4 ระดับ (Global, Organization, Project, Contract)

Rationale:

รองรับโครงสร้างองค์กรที่ซับซ้อน
ยืดหยุ่นในการกำหนดสิทธิ์
Most Permissive Rule (ใช้สิทธิ์สูงสุดที่มี)

Implementation:

CASL for Permission Rules
Redis Cache for Performance
Permission Checking at Guard Level

Related: ADR-004

📊 Architecture Diagrams

High-Level System Architecture

graph TB
    subgraph "Client Layer"
        Browser[Web Browser]
        Mobile[Mobile Browser]
    end

    subgraph "Presentation Layer"
        NPM[Nginx Proxy Manager<br/>SSL/TLS Termination]
    end

    subgraph "Application Layer"
        Frontend[Next.js Frontend<br/>lcbp3.np-dms.work]
        Backend[NestJS Backend<br/>backend.np-dms.work]
    end

    subgraph "Data Layer"
        MariaDB[(MariaDB 11.8<br/>Primary Database)]
        Redis[(Redis<br/>Cache + Queue)]
        Elastic[Elasticsearch<br/>Search Engine]
        Storage[File Storage<br/>/share/dms-data]
    end

    subgraph "Integration Layer"
        N8N[n8n Workflow]
        Email[Email Service]
        Line[LINE Notify]
    end

    Browser --> NPM
    Mobile --> NPM
    NPM --> Frontend
    NPM --> Backend

    Frontend --> Backend
    Backend --> MariaDB
    Backend --> Redis
    Backend --> Elastic
    Backend --> Storage
    Backend --> N8N

    N8N --> Email
    N8N --> Line

Request Flow (Simplified)

sequenceDiagram
    participant C as Client
    participant N as Nginx
    participant B as Backend
    participant R as Redis
    participant D as Database

    C->>N: HTTPS Request + JWT
    N->>B: Forward Request

    B->>B: Rate Limit Check
    B->>B: Input Validation
    B->>B: JWT Verification
    B->>R: Get Permissions
    R-->>B: Permission Data
    B->>B: RBAC Check

    B->>D: Query/Update
    D-->>B: Result

    B->>D: Audit Log
    B-->>C: JSON Response

Requirements

Implementation Plans

Data Specifications

Other Specifications

📈 Performance Targets

Metric	Target	Measurement
API Response Time	< 200ms	90th percentile (Simple CRUD)
Search Performance	< 500ms	Complex Search Queries
File Upload	< 30s	50MB file processing
Concurrent Users	100+	Simultaneous active users
Cache Hit Ratio	> 80%	Master Data caching
Uptime	99.5%	Monthly availability

🛡️ Security Standards

OWASP Top 10 Protection

Vulnerability	Protection Measure
SQL Injection	Parameterized Queries (TypeORM)
XSS	Input Sanitization + Output Encoding
CSRF	CSRF Tokens for State-Changing Ops
Broken Authentication	JWT + Secure Token Management
Security Misconfiguration	Security Headers (Helmet.js)
Sensitive Data Exposure	Encryption + Secure Storage
Insufficient Logging	Comprehensive Audit Logs

Rate Limiting

User Role	Limit	Scope
Anonymous	100 req/hour	IP Address
Viewer	500 req/hour	User ID
Editor	1000 req/hour	User ID
Document Control	2000 req/hour	User ID
Admin/Superadmin	5000 req/hour	User ID

🔄 Change History

Version	Date	Author	Changes
1.5.0	2025-11-30	Nattanin P.	Initial architecture specification
1.4.5	2025-11-29	-	Added security requirements
1.4.4	2025-11-28	-	Enhanced resilience patterns

📞 Questions & Feedback

Architecture Review

Tech Lead: [ระบุชื่อ]
Senior Architect: [ระบุชื่อ]

Contributing

กรุณาอ่าน CONTRIBUTING.md สำหรับแนวทางการมีส่วนร่วมในการพัฒนา Specifications

Issues & Discussions

LCBP3-DMS Architecture Specification v1.5.0

System Architecture • API Design • Data Model

Main README • Requirements • Implementation

README.md

📋 Architecture Specification

📊 Document Status

📚 Table of Contents

🎯 ภาพรวม (Overview)

Core Principles

Architecture Style

📖 เอกสารสถาปัตยกรรม

1. System Architecture

2. API Design

3. Data Model

🏗️ หลักการออกแบบ (Architecture Principles)

1. Separation of Concerns

2. Modular Architecture

3. Security Layers

4. Data Integrity Mechanisms

🛠️ Technology Stack

Frontend Stack

Backend Stack

Infrastructure Stack

🎯 Key Architectural Decisions

ADR-001: Unified Workflow Engine

ADR-002: Document Numbering Strategy

ADR-003: Two-Phase File Storage

ADR-004: 4-Level RBAC

📊 Architecture Diagrams

High-Level System Architecture

Request Flow (Simplified)

🔗 Related Documents

Requirements

Implementation Plans

Data Specifications

Other Specifications

📈 Performance Targets

🛡️ Security Standards

OWASP Top 10 Protection

Rate Limiting

🔄 Change History

📞 Questions & Feedback

Architecture Review

Contributing

Issues & Discussions