lcbp3/specs/02-architecture/system-architecture.md

# 🏗️ System Architecture Specification

---

**title:** 'System Architecture'
**version:** 1.5.0
**status:** first-draft
**owner:** Nattanin Peancharoen
**last_updated:** 2025-11-30
**related:**

- specs/01-requirements/02-architecture.md
- specs/01-requirements/06-non-functional.md
- specs/03-implementation/fullftack-js-v1.5.0.md

---

## 📋 ภาพรวม (Overview)

เอกสารนี้อธิบายสถาปัตยกรรมระบบ LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) ที่ใช้แนวทาง **Headless/API-First Architecture** พร้อมการ Deploy บน QNAP Server ผ่าน Container Station

## 🎯 Architecture Principles

### 1.1 Core Principles

1. **Data Integrity First:** ความถูกต้องของข้อมูลต้องมาก่อนทุกอย่าง
2. **Security by Design:** รักษาความปลอดภัยที่ทุกชั้น
3. **Scalability:** รองรับการเติบโตในอนาคต
4. **Resilience:** ทนทานต่อ Failure และ Recovery ได้รวดเร็ว
5. **Observability:** ติดตามและวิเคราะห์สถานะระบบได้ง่าย

### 1.2 Architecture Style

- **Headless CMS Architecture:** แยก Frontend และ Backend เป็นอิสระ
- **API-First:** Backend เป็น API Server ที่ Frontend หรือ Third-party สามารถเรียกใช้ได้
- **Microservices-Ready:** ออกแบบเป็น Modular Architecture พร้อมแยกเป็น Microservices ในอนาคต

## 🏢 Infrastructure & Deployment

### 2.1 Server Infrastructure

- **Server:** QNAP TS-473A
  - CPU: AMD Ryzen V1500B
  - RAM: 32GB
  - Storage: /share/dms-data
- **IP Address:** 159.192.126.103
- **Domain:** np-dms.work, <www.np-dms.work>
- **Containerization:** Docker & Docker Compose via Container Station
- **Development Environment:** VS Code/Cursor on Windows 11

### 2.2 Network Architecture

```mermaid
graph TB
    Internet[Internet] --> NPM[Nginx Proxy Manager<br/>npm.np-dms.work]
    NPM --> Frontend[Next.js Frontend<br/>lcbp3.np-dms.work]
    NPM --> Backend[NestJS Backend<br/>backend.np-dms.work]
    NPM --> PMA[phpMyAdmin<br/>pma.np-dms.work]
    NPM --> N8N[n8n Workflow<br/>n8n.np-dms.work]
    NPM --> Gitea[Gitea Git<br/>git.np-dms.work]

    Backend --> MariaDB[(MariaDB 11.8<br/>db.np-dms.work)]
    Backend --> Redis[(Redis Cache)]
    Backend --> Elastic[Elasticsearch]
    Backend --> Storage[File Storage<br/>/share/dms-data]

    N8N --> Line[LINE Notify]
    Backend --> Email[Email Server]
```

**Docker Network:**

- Network Name: `lcbp3`
- ทุก Service เชื่อมต่อผ่าน Internal Docker Network เพื่อความปลอดภัย

### 2.3 Configuration Management

> [!WARNING] > **ข้อจำกัดสำคัญ:** QNAP Container Station ไม่รองรับการใช้ `.env` files ในการกำหนด Environment Variables

**Configuration Strategy:**

1. **Production/Staging:**

   - ใช้ `docker-compose.yml` สำหรับกำหนด Environment Variables
   - ห้ามระบุ Sensitive Secrets (Password, Keys) ใน `docker-compose.yml` หลัก
   - ใช้ `docker-compose.override.yml` (gitignored) สำหรับ Secrets
   - พิจารณาใช้ Docker Secrets หรือ Hashicorp Vault

2. **Development:**

   - ใช้ `docker-compose.override.yml` สำหรับ Local Secrets
   - ไฟล์หลักใส่ค่า Dummy/Placeholder

3. **Validation:**
   - ใช้ Joi/Zod validate Environment Variables ตอน App Start
   - Throw Error ทันทีหากขาด Variable สำคัญ

## 🔧 Core Services

### 3.1 Service Overview

| Service           | Application Name | Domain              | Technology               | Purpose                     |
| :---------------- | :--------------- | :------------------ | :----------------------- | :-------------------------- |
| **Frontend**      | lcbp3-frontend   | lcbp3.np-dms.work   | Next.js 14+ (App Router) | Web Application UI          |
| **Backend**       | lcbp3-backend    | backend.np-dms.work | NestJS (TypeScript)      | API Server & Business Logic |
| **Database**      | lcbp3-db         | db.np-dms.work      | MariaDB 11.8             | Primary Database            |
| **DB Management** | lcbp3-db         | pma.np-dms.work     | phpMyAdmin               | Database Admin UI           |
| **Reverse Proxy** | lcbp3-npm        | npm.np-dms.work     | Nginx Proxy Manager      | Reverse Proxy & SSL         |
| **Workflow**      | lcbp3-n8n        | n8n.np-dms.work     | n8n                      | Workflow Automation         |
| **Git**           | git              | git.np-dms.work     | Gitea                    | Self-hosted Git             |
| **Cache**         | -                | -                   | Redis                    | Caching & Locking           |
| **Search**        | -                | -                   | Elasticsearch            | Full-text Search            |

### 3.2 Frontend (Next.js)

**Stack:**

- **Framework:** Next.js 14+ with App Router
- **Language:** TypeScript (ESM)
- **Styling:** Tailwind CSS + PostCSS
- **Components:** shadcn/ui
- **State Management:**
  - Server State: TanStack Query (React Query)
  - Form State: React Hook Form + Zod
  - UI State: useState/useReducer

**Responsibilities:**

- Render Web UI สำหรับผู้ใช้
- จัดการ User Interactions
- เรียก Backend API
- Client-side Validation
- Responsive Design (Desktop + Mobile)

### 3.3 Backend (NestJS)

**Stack:**

- **Framework:** NestJS (Node.js + TypeScript)
- **ORM:** TypeORM
- **Authentication:** JWT + Passport
- **Authorization:** CASL (RBAC)
- **Validation:** class-validator + class-transformer
- **Documentation:** Swagger/OpenAPI

**Responsibilities:**

- ให้บริการ RESTful API
- Business Logic Processing
- Authentication & Authorization
- Data Validation
- Database Operations
- File Upload Handling (Two-Phase Storage)
- Workflow Engine
- Background Jobs (Notifications, Cleanup)

### 3.4 Database (MariaDB 11.8)

**Features:**

- **JSON Support:** จัดเก็บ `details` fields (Dynamic Schema)
- **Virtual Columns:** Index JSON fields สำหรับ Performance
- **Partitioning:** สำหรับ `audit_logs` และ `notifications`
- **Optimistic Locking:** ใช้ `@VersionColumn()` ป้องกัน Race Condition

**Key Tables:**

- Users & Permissions: `users`, `roles`, `permissions`, `user_roles`
- Projects: `projects`, `organizations`, `contracts`, `project_parties`
- Documents: `correspondences`, `rfas`, `shop_drawings`, `contract_drawings`
- Workflow: `workflow_definitions`, `workflow_instances`, `workflow_history`
- Files: `attachments`, `correspondence_attachments`, etc.
- Audit: `audit_logs`

### 3.5 Redis

**Use Cases:**

1. **Distributed Locking:** Document Numbering, Critical Operations
2. **Session Caching:** User Permissions, Profile Data
3. **Master Data Cache:** Roles, Permissions, Organizations (TTL: 1 hour)
4. **Queue Management:** BullMQ for Background Jobs
5. **Rate Limiting:** Track API Request Counts

### 3.6 Elasticsearch

**Use Cases:**

- **Full-text Search:** Search across Correspondence, RFA, Drawings
- **Advanced Filtering:** Multi-criteria Search
- **Aggregations:** Statistics และ Dashboard Data

**Indexing Strategy:**

- Index อัตโนมัติเมื่อ Create/Update เอกสาร
- Async Indexing ผ่าน Queue (ไม่ Block Main Request)

## 🧱 Backend Module Architecture

### 4.1 Modular Design

```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]
        Trans[TransmittalModule<br/>Transmittals]
    end

    subgraph "Supporting Modules"
        Workflow[WorkflowEngineModule<br/>Unified Workflow]
        Numbering[DocumentNumberingModule<br/>Auto Numbering]
        Search[SearchModule<br/>Elasticsearch]
        Master[MasterModule<br/>Master Data]
        JSON[JsonSchemaModule<br/>JSON Validation]
    end

    Corr --> Workflow
    RFA --> Workflow
    Circ --> Workflow

    Corr --> Numbering
    RFA --> Numbering

    Search --> Corr
    Search --> RFA
    Search --> Drawing
```

### 4.2 Module Descriptions

#### 4.2.1 CommonModule

**Responsibilities:**

- Database Configuration
- FileStorageService (Two-Phase Upload)
- AuditLogService
- NotificationService
- Shared DTOs, Guards, Interceptors

#### 4.2.2 AuthModule

**Responsibilities:**

- JWT Token Management
- Authentication Guards
- 4-Level Permission Checking:
  - Global (Superadmin)
  - Organization
  - Project
  - Contract
- Token Refresh & Revocation

#### 4.2.3 UserModule

**Responsibilities:**

- User CRUD Operations
- Role Assignment
- Permission Management
- User Profile Management

#### 4.2.4 ProjectModule

**Responsibilities:**

- Project Management
- Contract Management
- Organization Management
- Project Parties & Contract Parties

#### 4.2.5 CorrespondenceModule

**Responsibilities:**

- Correspondence CRUD
- Revision Management
- Attachment Handling
- Workflow Integration (Routing)

#### 4.2.6 RfaModule

**Responsibilities:**

- RFA CRUD
- RFA Item Management
- Workflow Integration (Approval Process)
- Respond/Approve Actions

#### 4.2.7 DrawingModule

**Responsibilities:**

- Shop Drawing Management
- Contract Drawing Management
- Drawing Categories
- Revision Tracking
- Drawing References

#### 4.2.8 CirculationModule

**Responsibilities:**

- Circulation Sheet Management
- Circulation Templates
- Assignees Management
- Workflow Integration (Internal Circulation)

#### 4.2.9 WorkflowEngineModule (Core)

> [!IMPORTANT] > **Unified Workflow Engine** - ระบบกลางสำหรับจัดการ Workflow ทั้งหมด

**Features:**

- DSL-Based Workflow Definitions (JSON Configuration)
- State Machine Management
- Workflow Instance Tracking
- History & Audit Trail
- Workflow Versioning

**Entities:**

- `WorkflowDefinition`: กำหนด Workflow Template
- `WorkflowInstance`: Instance ที่กำลังรัน
- `WorkflowHistory`: ประวัติการเปลี่ยน State

**Integration:**

- CorrespondenceModule → Routing Workflow
- RfaModule → Approval Workflow
- CirculationModule → Internal Circulation Workflow

#### 4.2.10 DocumentNumberingModule (Internal)

**Responsibilities:**

- Auto-generate Document Numbers
- Token-Based Generator: `{CONTRACT}-{TYPE}-{DISCIPLINE}-{SEQ:4}`
- **Double-Lock Mechanism:**
  - Layer 1: Redis Distributed Lock
  - Layer 2: Optimistic Database Lock (`@VersionColumn()`)

**Algorithm:**

1. Parse Template → Identify Required Tokens
2. Acquire Redis Lock (Key: `project_id:type_id:discipline_id:year`)
3. Query `document_number_counters` Table
4. Increment Counter (Check Version)
5. Generate Final Number
6. Release Lock
7. Retry on Conflict (Exponential Backoff)

#### 4.2.11 SearchModule

**Responsibilities:**

- Elasticsearch Integration
- Full-text Search across Documents
- Advanced Filtering
- Search Result Aggregation

#### 4.2.12 JsonSchemaModule (Internal)

**Responsibilities:**

- JSON Schema Validation (AJV)
- Schema Versioning & Migration
- Dynamic Schema Generation
- Data Transformation

## 📊 Data Flow Architecture

### 5.1 Main Request Flow

```mermaid
sequenceDiagram
    participant Client as Client (Browser)
    participant NPM as Nginx Proxy
    participant BE as Backend (NestJS)
    participant Redis as Redis Cache
    participant DB as MariaDB
    participant ES as Elasticsearch

    Client->>NPM: HTTP Request + JWT
    NPM->>BE: Forward Request

    BE->>BE: Rate Limit Check
    BE->>BE: Validate Input (DTO)
    BE->>BE: JWT Auth Guard
    BE->>Redis: Get User Permissions
    Redis-->>BE: Permission Data
    BE->>BE: RBAC Guard (Check Permission)

    BE->>DB: Query Data
    DB-->>BE: Return Data

    BE->>BE: Business Logic Processing
    BE->>DB: Save Changes (Transaction)
    BE->>ES: Index for Search
    BE->>Redis: Invalidate Cache

    BE->>DB: Audit Log
    BE-->>Client: JSON Response
```

### 5.2 File Upload Flow (Two-Phase Storage)

> [!IMPORTANT] > **Two-Phase Storage** ป้องกัน Orphan Files และรักษา Data Integrity

```mermaid
sequenceDiagram
    participant Client
    participant Backend
    participant ClamAV as Virus Scanner
    participant TempStorage as Temp Storage
    participant PermStorage as Permanent Storage
    participant DB as Database

    Client->>Backend: Upload File
    Backend->>ClamAV: Scan Virus
    ClamAV-->>Backend: Scan Result (CLEAN/INFECTED)

    alt File is CLEAN
        Backend->>TempStorage: Save to temp/
        Backend-->>Client: Return temp_id

        Client->>Backend: POST Create Document (include temp_id)
        Backend->>DB: BEGIN Transaction
        Backend->>DB: Create Document Record
        Backend->>PermStorage: Move temp/ → permanent/{YYYY}/{MM}/
        Backend->>DB: Create Attachment Record
        Backend->>DB: COMMIT Transaction
        Backend-->>Client: Success Response
    else File is INFECTED
        Backend-->>Client: Error: Virus Detected
    end

    Note over Backend,TempStorage: Cron Job: Delete temp files > 24h
```

### 5.3 Document Numbering Flow

```mermaid
sequenceDiagram
    participant Service as Correspondence Service
    participant Numbering as Numbering Service
    participant Redis
    participant DB as MariaDB

    Service->>Numbering: generateNextNumber(context)
    Numbering->>Numbering: Parse Template
    Numbering->>Redis: ACQUIRE Lock (project:type:year)

    alt Lock Acquired
        Redis-->>Numbering: Lock Success
        Numbering->>DB: SELECT counter (with version)
        DB-->>Numbering: current_number, version
        Numbering->>DB: UPDATE counter SET last_number = X, version = version + 1 WHERE version = old_version

        alt Update Success
            DB-->>Numbering: Success
            Numbering->>Numbering: Generate Final Number
            Numbering->>Redis: RELEASE Lock
            Numbering-->>Service: Document Number
        else Version Conflict (Race Condition)
            DB-->>Numbering: Update Failed
            Numbering->>Redis: RELEASE Lock
            Numbering->>Numbering: Retry (Exponential Backoff)
        end
    else Lock Failed
        Redis-->>Numbering: Lock Timeout
        Numbering->>Numbering: Retry or Fail
    end
```

### 5.4 Workflow Execution Flow

```mermaid
sequenceDiagram
    participant User
    participant Module as Correspondence Module
    participant Engine as Workflow Engine
    participant DB
    participant Notify as Notification Service

    User->>Module: Create Correspondence
    Module->>Engine: createWorkflowInstance(definition_id, entity_id)
    Engine->>DB: Create workflow_instance
    Engine->>DB: Set initial state
    Engine-->>Module: Instance Created
    Module-->>User: Success

    User->>Module: Execute Action (e.g., "Send")
    Module->>Engine: executeTransition(instance_id, action)
    Engine->>DB: Check current state
    Engine->>Engine: Validate transition (DSL)

    alt Transition Valid
        Engine->>DB: Update state
        Engine->>DB: Create workflow_history
        Engine->>Notify: Trigger Notification
        Notify->>Notify: Queue Email/Line
        Engine-->>Module: Transition Success
        Module-->>User: Action Completed
    else Invalid Transition
        Engine-->>Module: Error: Invalid State Transition
        Module-->>User: Error Response
    end
```

## 🛡️ Security Architecture

### 6.1 Security Layers

```mermaid
graph TB
    subgraph "Layer 1: Network Security"
        SSL[SSL/TLS<br/>Nginx Proxy Manager]
        Firewall[Firewall Rules<br/>QNAP]
    end

    subgraph "Layer 2: Application Security"
        RateLimit[Rate Limiting]
        CSRF[CSRF Protection]
        XSS[XSS Prevention]
        Input[Input Validation]
    end

    subgraph "Layer 3: Authentication"
        JWT[JWT Tokens]
        Refresh[Token Refresh]
        Revoke[Token Revocation]
    end

    subgraph "Layer 4: Authorization"
        RBAC[4-Level RBAC]
        Guards[Permission Guards]
        CASL[CASL Rules]
    end

    subgraph "Layer 5: Data Security"
        Encrypt[Data Encryption]
        Audit[Audit Logs]
        Backup[Backups]
    end

    subgraph "Layer 6: File Security"
        Virus[Virus Scanning]
        FileType[Type Validation]
        FileAccess[Access Control]
    end
```

### 6.2 Authentication & Authorization Details

**JWT Token Structure:**

```json
{
  "sub": "user_id",
  "scope": "organization_id|project_id|contract_id",
  "iat": 1638360000,
  "exp": 1638388800
}
```

**Permission Checking Logic:**

1. Extract JWT from `Authorization: Bearer <token>`
2. Validate Token (Signature, Expiration)
3. Get User Permissions from Redis Cache (Key: `user:{user_id}:permissions`)
4. Check Permission based on Context:
   - Global Permission (Superadmin)
   - Organization Permission
   - Project Permission (if in project context)
   - Contract Permission (if in contract context)
5. Allow if **any level** grants permission (Most Permissive)

### 6.3 Rate Limiting

| Endpoint Category | Limit         | Tracking   |
| :---------------- | :------------ | :--------- |
| Anonymous         | 100 req/hour  | IP Address |
| Authentication    | 10 req/min    | IP Address |
| File Upload       | 50 req/hour   | User ID    |
| Search            | 500 req/hour  | User ID    |
| Viewer            | 500 req/hour  | User ID    |
| Editor            | 1000 req/hour | User ID    |
| Document Control  | 2000 req/hour | User ID    |
| Admin             | 5000 req/hour | User ID    |

**Implementation:** `rate-limiter-flexible` library with Redis backend

### 6.4 Input Validation

**Frontend (Client-Side):**

- React Hook Form + Zod Schema Validation
- Sanitize User Inputs before Display

**Backend (Server-Side):**

- class-validator DTOs
- Whitelist Validation (`@ValidateIf`, `@IsEnum`, etc.)
- Transform Pipes

**File Upload Validation:**

1. **File Type Validation:**

   - White-list: PDF, DWG, DOCX, XLSX, ZIP
   - Magic Number Verification (ไม่ใช่แค่ extension)

2. **File Size Validation:**

   - Maximum: 50MB per file

3. **Virus Scanning:**
   - ClamAV Integration
   - Scan before saving to temp storage

### 6.5 OWASP Top 10 Protection

| Vulnerability                     | Protection Measure                   |
| :-------------------------------- | :----------------------------------- |
| SQL Injection                     | Parameterized Queries (TypeORM)      |
| XSS                               | Input Sanitization + Output Encoding |
| CSRF                              | CSRF Tokens (State-changing ops)     |
| Broken Auth                       | JWT + Secure Token Management        |
| Security Misconfiguration         | Security Headers (Helmet.js)         |
| Sensitive Data Exposure           | Encryption + Secure Storage          |
| Insufficient Logging              | Comprehensive Audit Logs             |
| Insecure Deserialization          | Input Validation                     |
| Using Known Vulnerable Components | Regular Dependency Updates           |

## 📈 Performance & Scalability

### 7.1 Caching Strategy

| Data Type        | Cache Location | TTL     | Invalidation              |
| :--------------- | :------------- | :------ | :------------------------ |
| User Permissions | Redis          | 30 min  | On role/permission change |
| Master Data      | Redis          | 1 hour  | On update                 |
| Search Results   | Redis          | 15 min  | Time-based                |
| File Metadata    | Redis          | 1 hour  | On file update            |
| Session Data     | Redis          | 8 hours | On logout                 |

### 7.2 Database Optimization

**Indexes:**

- Foreign Keys (Auto-indexed)
- Search Columns (`idx_cor_project`, `idx_rfa_status`, etc.)
- JSON Virtual Columns (for frequently queried JSON fields)

**Partitioning:**

- `audit_logs`: Partitioned by Year
- `notifications`: Partitioned by Month
- Automated Partition Creation (Cron Job)

**Query Optimization:**

- Use Views for Complex Queries (`v_current_correspondences`, `v_user_tasks`)
- Pagination for Large Datasets
- Eager/Lazy Loading Strategy

### 7.3 Performance Targets

| Metric                              | Target  | Measurement    |
| :---------------------------------- | :------ | :------------- |
| API Response Time (90th percentile) | < 200ms | Simple CRUD    |
| Search Query Performance            | < 500ms | Complex Search |
| File Upload Processing              | < 30s   | 50MB file      |
| Concurrent Users                    | 100+    | Simultaneous   |
| Cache Hit Ratio                     | > 80%   | Master Data    |
| Application Startup                 | < 30s   | Cold Start     |

## 🔄 Resilience & Error Handling

### 8.1 Resilience Patterns

**Circuit Breaker:**

- Applied to: Elasticsearch, Email Service, LINE Notify
- Threshold: 5 failures in 1 minute
- Timeout: 30 seconds
- Recovery: Half-open after 1 minute

**Retry Mechanism:**

- Strategy: Exponential Backoff
- Max Retries: 3
- Applied to: External API Calls, Document Numbering

**Graceful Degradation:**

- Search Service Down → Return cached results or basic search
- Email Service Down → Queue for later retry
- LINE Notify Down → Log error, continue operation

### 8.2 Error Handling

**Backend:**

- Global Exception Filter
- Structured Error Response Format
- Error Logging with Context (Winston)
- Don't Expose Internal Details in Error Messages

**Frontend:**

- Error Boundaries (React)
- Toast Notifications
- Fallback UI Components
- Retry Mechanisms for Failed Requests

## 📊 Monitoring & Observability

### 9.1 Health Checks

**Endpoints:**

```
GET /health          # Overall health
GET /health/ready    # Readiness probe
GET /health/live     # Liveness probe
```

**Checks:**

- Database Connection
- Redis Connection
- Elasticsearch Connection
- Disk Space
- Memory Usage

### 9.2 Metrics Collection

**Application Metrics:**

- Request Rate (req/sec)
- Response Time (p50, p90, p99)
- Error Rate
- Active Connections

**Business Metrics:**

- Documents Created per Day
- Workflow Completion Rate
- User Activity
- Search Query Performance

**Infrastructure Metrics:**

- CPU Usage
- Memory Usage
- Disk I/O
- Network Throughput

### 9.3 Logging Strategy

> [!WARNING] > **QNAP Storage Constraints:** ต้องจำกัดปริมาณ Logs

**Log Levels:**

- **Production:** WARN and ERROR only
- **Staging:** INFO for critical business flows
- **Development:** DEBUG allowed

**Structured Logging:**

```json
{
  "timestamp": "2025-11-30T13:48:20Z",
  "level": "INFO",
  "service": "backend",
  "module": "CorrespondenceModule",
  "action": "create",
  "user_id": 1,
  "ip_address": "192.168.1.100",
  "duration_ms": 45,
  "message": "Correspondence created successfully"
}
```

**Log Rotation:**

- Rotate Daily
- Keep 7 days
- Compress Old Logs

### 9.4 Audit Logging

**Scope:**

- All CRUD Operations on Critical Data
- Permission Changes
- Login Attempts (Success/Failure)
- File Downloads
- Workflow State Changes

**Audit Log Fields:**

- `user_id`
- `action` (e.g., `correspondence.create`)
- `entity_type`, `entity_id`
- `old_values`, `new_values` (for updates)
- `ip_address`, `user_agent`
- `timestamp`

## 💾 Backup & Disaster Recovery

### 10.1 Backup Strategy

**Database Backup:**

- **Frequency:** Daily (Automated)
- **Method:** Full Backup + Transaction Logs
- **Retention:** 30 days
- **Tool:** QNAP HBS 3 or mysqldump

**File Storage Backup:**

- **Frequency:** Daily
- **Path:** `/share/dms-data`
- **Method:** Incremental Backup
- **Retention:** 30 days
- **Tool:** QNAP Snapshot or rsync

### 10.2 Disaster Recovery

**Recovery Objectives:**

- **RTO (Recovery Time Objective):** < 4 hours
- **RPO (Recovery Point Objective):** < 1 hour

**Recovery Procedures:**

1. **Database Restoration:**

   - Restore latest full backup
   - Apply transaction logs to point-in-time
   - Verify data integrity

2. **File Storage Restoration:**

   - Restore from QNAP snapshot
   - Verify file permissions

3. **Application Redeployment:**

   - Deploy from known-good Docker images
   - Verify health checks

4. **Data Integrity Verification:**
   - Run consistency checks
   - Verify critical business data

## 🏗️ Deployment Architecture

### 11.1 Container Deployment

**Docker Compose Services:**

```yaml
services:
  frontend:
    image: lcbp3-frontend:latest
    networks: [lcbp3]
    depends_on: [backend]

  backend:
    image: lcbp3-backend:latest
    networks: [lcbp3]
    depends_on: [mariadb, redis, elasticsearch]

  mariadb:
    image: mariadb:10.11
    networks: [lcbp3]
    volumes: [/share/dms-data/mysql:/var/lib/mysql]

  redis:
    image: redis:7-alpine
    networks: [lcbp3]

  elasticsearch:
    image: elasticsearch:8.x
    networks: [lcbp3]

  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:latest
    networks: [lcbp3]
    ports: [80:80, 443:443]
```

### 11.2 CI/CD Pipeline (Future)

```mermaid
graph LR
    Git[Gitea Repository] --> Build[Build & Test]
    Build --> StagingDeploy[Deploy to Staging]
    StagingDeploy --> Test[Run E2E Tests]
    Test --> Manual[Manual Approval]
    Manual --> ProdDeploy[Deploy to Production]
    ProdDeploy --> Monitor[Monitor & Alert]
```

## 🎯 Future Enhancements

### 12.1 Scalability Improvements

- [ ] Separate into Microservices (when needed)
- [ ] Add Load Balancer (HAProxy/Nginx)
- [ ] Database Replication (Master-Slave)
- [ ] Message Queue (RabbitMQ/Kafka) for async processing

### 12.2 Advanced Features

- [ ] AI-Powered Document Classification
- [ ] Advanced Analytics & Reporting
- [ ] Mobile Native Apps
- [ ] Blockchain Integration for Document Integrity

### 12.3 Infrastructure

- [ ] Multi-Region Deployment
- [ ] CDN for Static Assets
- [ ] Automated Failover
- [ ] Blue-Green Deployment

---

**Document Control:**

- **Version:** 1.5.1
- **Status:** Active
- **Last Updated:** 2025-12-02
- **Owner:** Nattanin Peancharoen

```

```