EDMS/docs/Technical_Guide.md

# Electronic Document Management System (EDMS) - Technical Guide

## Table of Contents
1. [System Overview](#system-overview)
2. [Architecture](#architecture)
3. [Technology Stack](#technology-stack)
4. [Database Schema](#database-schema)
5. [Installation & Setup](#installation--setup)
6. [Development Environment](#development-environment)
7. [Component Structure](#component-structure)
8. [API & Data Management](#api--data-management)
9. [DMS Settings System](#dms-settings-system)
10. [Site Settings Integration](#site-settings-integration)
11. [Security & Authentication](#security--authentication)
12. [Deployment](#deployment)
13. [Maintenance & Monitoring](#maintenance--monitoring)
14. [Extension & Customization](#extension--customization)

## System Overview

The Electronic Document Management System (EDMS) is a modern web application built with Nuxt.js 3 and Vue.js 3, designed to provide a comprehensive document management solution for organizations. The system implements a hierarchical document organization structure with role-based access control (RBAC) and supports integration with external authentication providers.

### Key Technical Features
- **Modern Frontend**: Vue.js 3 with Composition API and script setup syntax
- **SSR/SPA Support**: Nuxt.js 3 for optimal performance and SEO
- **Database**: Prisma ORM with MySQL support and comprehensive schema
- **Styling**: TailwindCSS with custom Rs component system
- **State Management**: Pinia for reactive state management with persistence
- **Authentication**: Flexible authentication with Authentik integration and role-based access control
- **File Management**: Server-side file handling with metadata and versioning
- **Real-time Features**: Vue reactivity for live updates and notifications
- **Responsive Design**: Mobile-first approach with adaptive layouts
- **Configurable System**: Comprehensive settings management for DMS and site configuration

## Architecture

### System Architecture
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (Nuxt.js)     │◄──►│   (Server API)  │◄──►│   (MySQL)       │
│                 │    │                 │    │                 │
│ • Vue.js 3      │    │ • Prisma ORM    │    │ • User Data     │
│ • TailwindCSS   │    │ • File System   │    │ • Documents     │
│ • Pinia Store   │    │ • Authentication│    │ • Permissions   │
│ • Rs Components │    │ • API Routes    │    │ • Audit Logs    │
│ • Settings UI   │    │ • Settings API  │    │ • DMS Settings  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        │              ┌─────────────────┐             │
        │              │ File Storage    │             │
        └──────────────►│ • Documents     │◄────────────┘
                       │ • Versions      │
                       │ • Thumbnails    │
                       │ • Temp Files    │
                       └─────────────────┘
```

### Application Flow
1. **Authentication**: User authenticates via configured authentication provider
2. **Authorization**: System validates user permissions against RBAC rules
3. **Configuration Loading**: System loads DMS and site settings from database
4. **Navigation**: User navigates document hierarchy with access level tabs
5. **Data Fetching**: Pinia store manages API calls with caching and error handling
6. **Rendering**: Vue components render UI with reactive updates
7. **File Operations**: Server handles secure file upload/download/preview
8. **Access Control**: System enforces granular document permissions
9. **Audit Trail**: All actions are logged for compliance and security
10. **Settings Management**: Administrators configure system behavior through settings UI

## Technology Stack

### Frontend Dependencies
```json
{
  "core": {
    "nuxt": "^3.6.5",
    "vue": "^3.x",
    "@pinia/nuxt": "^0.4.11",
    "@pinia-plugin-persistedstate/nuxt": "^1.1.1"
  },
  "styling": {
    "@nuxtjs/tailwindcss": "^6.8.0",
    "sass": "^1.62.0",
    "postcss-import": "^15.1.0"
  },
  "forms": {
    "@formkit/nuxt": "^1.0.0",
    "@formkit/themes": "^1.0.0",
    "@formkit/addons": "^1.0.0",
    "@formkit/pro": "^0.115.3"
  },
  "ui": {
    "apexcharts": "^3.36.0",
    "vue3-apexcharts": "^1.4.1",
    "@vueuse/core": "^9.5.0",
    "@vueuse/nuxt": "^9.5.0",
    "floating-vue": "^2.0.0-beta.24",
    "vue3-dropzone": "^2.0.1"
  },
  "utilities": {
    "luxon": "^3.1.0",
    "uuid": "^10.0.0",
    "crypto-js": "^4.1.1",
    "@shimyshack/uid": "^0.1.7"
  }
}
```

### Backend Dependencies
```json
{
  "database": {
    "@prisma/client": "^5.1.1",
    "prisma": "^5.1.1"
  },
  "authentication": {
    "jsonwebtoken": "^8.5.1"
  },
  "file-handling": {
    "jspdf": "^2.5.1"
  },
  "security": {
    "nuxt-security": "^0.13.0"
  }
}
```

### Development Tools
- **ESLint**: Code linting with Vue.js specific rules
- **TypeScript**: Type safety with Nuxt TypeScript integration
- **Prettier**: Consistent code formatting
- **Vite**: Lightning-fast build tool and HMR
- **PostCSS**: Advanced CSS processing with plugins

## Database Schema

### Core Models

#### User Management
```prisma
model user {
  userID           Int                @id @default(autoincrement())
  userSecretKey    String?            @db.VarChar(255)
  userUsername     String?            @db.VarChar(255)
  userPassword     String?            @db.VarChar(255)
  userFullName     String?            @db.VarChar(255)
  userEmail        String?            @db.VarChar(255)
  userPhone        String?            @db.VarChar(255)
  userStatus       String?            @db.VarChar(255)
  userCreatedDate  DateTime?          @default(now()) @db.DateTime(0)
  userModifiedDate DateTime?          @db.DateTime(0)
  
  // Relationships
  audit            audit[]
  userrole         userrole[]
}

model role {
  roleID              Int                @id @default(autoincrement())
  roleName            String?            @db.VarChar(255)
  roleDescription     String?            @db.VarChar(255)
  roleStatus          String?            @db.VarChar(255)
  roleCreatedDate     DateTime?          @db.DateTime(0)
  roleModifiedDate    DateTime?          @db.DateTime(0)
  
  userrole            userrole[]
}

model userrole {
  userRoleID          Int      @id @default(autoincrement())
  userRoleUserID      Int      @default(0)
  userRoleRoleID      Int      @default(0)
  userRoleCreatedDate DateTime @db.DateTime(0)
  
  role                role     @relation(fields: [userRoleRoleID], references: [roleID])
  user                user     @relation(fields: [userRoleUserID], references: [userID])
}
```

#### Organization Structure
```prisma
model organization {
  org_id       Int          @id @default(autoincrement())
  org_name     String       @unique @db.VarChar(255)
  org_address1 String?      @db.VarChar(255)
  org_address2 String?      @db.VarChar(255)
  org_postcode Int?
  org_state    String?      @db.VarChar(100)
  org_country  String?      @db.VarChar(100)
  org_active   Int?
  
  departments  department[]
}

model department {
  dp_id        Int          @id @default(autoincrement())
  dp_name      String       @db.VarChar(255)
  org_id       Int
  
  organization organization @relation(fields: [org_id], references: [org_id])
  cabinets     cabinets[]
  users        sys_user[]
}

model cabinets {
  cb_id        Int         @id @default(autoincrement())
  cb_name      String      @unique @db.VarChar(255)
  cb_parent_id Int?
  cb_private   Int?        @default(0)
  cb_owner     Int?
  dp_id        Int?
  created_at   DateTime?   @db.DateTime(0)
  modified_at  DateTime?   @db.DateTime(0)
  
  department   department? @relation(fields: [dp_id], references: [dp_id])
}
```

#### Site Settings Configuration
```prisma
model site_settings {
  settingID                Int       @id @default(autoincrement())
  siteName                 String?   @default("corradAF") @db.VarChar(255)
  siteNameFontSize         Int?      @default(18)
  siteDescription          String?   @db.Text
  siteLogo                 String?   @db.VarChar(500)
  siteLoadingLogo          String?   @db.VarChar(500)
  siteFavicon              String?   @db.VarChar(500)
  siteLoginLogo            String?   @db.VarChar(500)
  showSiteNameInHeader     Boolean?  @default(true)
  customCSS                String?   @db.LongText
  themeMode                String?   @default("biasa") @db.VarChar(100)
  customThemeFile          String?   @db.VarChar(500)
  currentFont              String?   @db.VarChar(100)
  fontSource               String?   @db.VarChar(100)
  seoTitle                 String?   @db.VarChar(255)
  seoDescription           String?   @db.Text
  seoKeywords              String?   @db.Text
  seoAuthor                String?   @db.VarChar(255)
  seoOgImage               String?   @db.VarChar(500)
  seoTwitterCard           String?   @default("summary_large_image") @db.VarChar(100)
  seoCanonicalUrl          String?   @db.VarChar(500)
  seoRobots                String?   @default("index, follow") @db.VarChar(100)
  seoGoogleAnalytics       String?   @db.VarChar(255)
  seoGoogleTagManager      String?   @db.VarChar(255)
  seoFacebookPixel         String?   @db.VarChar(255)
  settingCreatedDate       DateTime? @default(now()) @db.DateTime(0)
  settingModifiedDate      DateTime? @default(now()) @db.DateTime(0)
}
```

#### DMS Settings Configuration
```prisma
model dms_settings {
  settingID                     Int       @id @default(autoincrement())
  
  // User & Access Management
  userRoles                     String?   @db.Text
  rbacEnabled                   Boolean?  @default(true)
  userGroups                    String?   @db.Text
  permissionView                Boolean?  @default(true)
  permissionEdit                Boolean?  @default(true)
  permissionDelete              Boolean?  @default(false)
  permissionDownload            Boolean?  @default(true)
  permissionShare               Boolean?  @default(true)
  ssoEnabled                    Boolean?  @default(false)
  mfaRequired                   Boolean?  @default(false)
  ldapIntegration               Boolean?  @default(false)
  sessionTimeout                Int?      @default(8)
  
  // Document & Folder Settings
  folderMaxDepth                Int?      @default(5)
  folderDefaultStructure        String?   @db.Text
  folderTemplates               String?   @db.Text
  namingAutoGenerate            Boolean?  @default(true)
  namingMandatoryFields         String?   @db.Text
  namingPattern                 String?   @default("{department}_{title}_{date}") @db.VarChar(255)
  retentionEnabled              Boolean?  @default(true)
  retentionDefaultDays          Int?      @default(2555)
  retentionArchiveBeforeDelete  Boolean?  @default(true)
  versionControlEnabled         Boolean?  @default(true)
  versionControlMaxVersions     Int?      @default(10)
  versionControlAutoVersioning  Boolean?  @default(true)
  
  // Metadata & Tagging
  metadataCustomFields          String?   @db.LongText
  taggingPredefinedTags         String?   @db.Text
  taggingUserGeneratedTags      Boolean?  @default(true)
  taggingTagSuggestions         Boolean?  @default(true)
  classificationAutoEnabled     Boolean?  @default(true)
  classificationRules           String?   @db.Text
  
  // Workflow & Automation
  workflowApprovalEnabled       Boolean?  @default(true)
  workflowDefaultFlow           String?   @default("department-head-approval") @db.VarChar(255)
  workflowCustomFlows           String?   @db.Text
  notificationEmail             Boolean?  @default(true)
  notificationInApp             Boolean?  @default(true)
  notificationUploadAlerts      Boolean?  @default(true)
  notificationDeadlineReminders Boolean?  @default(true)
  automationTriggers            String?   @db.Text
  automationActions             String?   @db.Text
  
  // Upload & Storage Settings
  uploadAllowedFileTypes        String?   @db.Text
  uploadBlockedFileTypes        String?   @db.Text
  uploadFileSizeLimit           Int?      @default(100)
  uploadQuotaPerUser            Int?      @default(5000)
  uploadQuotaPerGroup           Int?      @default(50000)
  uploadQuotaPerProject         Int?      @default(100000)
  storageType                   String?   @default("local") @db.VarChar(100)
  storagePath                   String?   @default("/var/uploads/edms") @db.VarChar(500)
  storageBackupEnabled          Boolean?  @default(true)
  storageCompressionEnabled     Boolean?  @default(false)
  
  // System Settings
  systemTimezone                String?   @default("Asia/Kuala_Lumpur") @db.VarChar(100)
  systemBackupSchedule          String?   @default("daily") @db.VarChar(100)
  systemLogLevel                String?   @default("info") @db.VarChar(100)
  systemMaintenanceMode         Boolean?  @default(false)
  systemAutoUpdates             Boolean?  @default(false)
  systemMonitoring              Boolean?  @default(true)
  systemPerformanceMetrics      Boolean?  @default(true)
  
  settingCreatedDate            DateTime? @default(now()) @db.DateTime(0)
  settingModifiedDate           DateTime? @default(now()) @db.DateTime(0)
}
```

#### Audit Trail
```prisma
model audit {
  auditID          Int       @id @default(autoincrement())
  auditIP          String?   @db.VarChar(255)
  auditURL         String?   @db.VarChar(255)
  auditURLMethod   String?   @db.VarChar(255)
  auditURLPayload  String?   @db.Text
  auditCreatedDate DateTime? @default(now()) @db.DateTime(0)
  auditAction      String?   @db.VarChar(255)
  auditDetails     String?   @db.Text
  auditUserID      Int?
  auditUsername    String?   @db.VarChar(255)
  
  user             user?     @relation(fields: [auditUserID], references: [userID])
}
```

## Installation & Setup

### Prerequisites
- Node.js 18+ with npm/yarn/pnpm
- MySQL 8.0+ or PostgreSQL 13+
- Git for version control

### Environment Configuration
Create a `.env` file in the project root:
```bash
# Database Configuration
DATABASE_URL="mysql://username:password@localhost:3306/edms_db"

# Authentication Settings
JWT_SECRET="your-super-secret-jwt-key"
AUTH_PROVIDER="local" # or "authentik", "ldap"

# File Storage
UPLOAD_PATH="/var/uploads/edms"
MAX_FILE_SIZE="100" # MB

# Application Settings
NUXT_SECRET_KEY="your-nuxt-secret-key"
NUXT_PUBLIC_API_BASE="/api"
```

### Database Setup
```bash
# Install dependencies
npm install

# Generate Prisma client
npx prisma generate

# Apply database migrations
npx prisma db push

# Seed initial data (optional)
npx prisma db seed
```

### Development Server
```bash
# Start development server
npm run dev

# Access application
# http://localhost:3000
```

## Component Structure

### Core Components

The EDMS is organized into several key component directories:

#### DMS Explorer Components
- **`components/dms/explorer/`**: Main document exploration interface
  - `DMSExplorer.vue`: Main document explorer component with folder navigation and document viewing
  - `DMSFileViewer.vue`: Document preview and viewing component
  - `DMSNavigation.vue`: Navigation tree and breadcrumbs
  - `DMSSearchBar.vue`: Advanced search component

#### Dialog Components
- **`components/dms/dialogs/`**: Modal dialogs for user interactions
  - `DMSUploadDialog.vue`: File upload with metadata tagging and validation
  - `DMSCreateNewDialog.vue`: Create new cabinets, drawers, folders and subfolders
  - `DMSAccessRequestDialog.vue`: Request access to restricted content
  - `DMSAccessApprovalDialog.vue`: Approve/reject access requests with notes

#### Access Management Components
- **`components/dms/workflows/`**: Access control and workflows
  - `DMSAccessRequestTracker.vue`: KPI tracking for access requests with metrics visualization
  - `DMSApprovalQueue.vue`: Access request approval management interface
  - `DMSRoleManager.vue`: Role management interface with Authentik integration

#### Admin Components
- **`components/dms/admin/`**: Administrative interfaces
  - `DMSAdminDashboard.vue`: KPI metrics and system overview with performance charts
  - `DMSAccessManagement.vue`: Comprehensive access management for documents
  - `DMSSystemSettings.vue`: System configuration interface

### Page Components

The system includes several key page components:

#### Main DMS Pages
- **`pages/dms/index.vue`**: Main document explorer page
- **`pages/dms/admin-dashboard.vue`**: Administrative dashboard with KPIs
- **`pages/dms/access-management.vue`**: Access request management interface
- **`pages/dms/role-management.vue`**: Role-based access control management
- **`pages/dms/switch-roles.vue`**: Role switching for testing and administrative purposes
- **`pages/dms/settings.vue`**: DMS settings configuration

### Store Implementation

State management is handled through Pinia stores:

#### DMS Store
- **`stores/dms.js`**: Core DMS functionality and state management
  - User information and authentication
  - Document and cabinet management
  - Role-based access control
  - Access request workflows
  - System settings and configuration
  - File uploads and metadata management

#### Global Store
- **`stores/global.js`**: Application-wide state management
  - Theme and UI preferences
  - Global notifications
  - Application state
  - User session management

## API & Data Management

### API Route Structure
```
server/api/
├── dms/
│   └── settings.js               # DMS configuration API
├── devtool/
│   └── config/
│       ├── site-settings.js      # Site settings API
│       ├── upload-file.js        # File upload handling
│       └── add-custom-theme.js   # Theme management
└── [...other API routes]
```

### DMS Settings API
The DMS settings API provides comprehensive configuration management:

#### GET `/api/dms/settings`
Retrieves current DMS settings with automatic defaults if none exist.

**Response Structure:**
```json
{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "access": {
      "userRoles": ["Admin", "Editor", "Viewer", "Uploader"],
      "rbacEnabled": true,
      "userGroups": ["HR Department", "Finance", "IT", "Legal"],
      "permissions": {
        "view": true,
        "edit": true,
        "delete": false,
        "download": true,
        "share": true
      },
      "authentication": {
        "ssoEnabled": false,
        "mfaRequired": false,
        "ldapIntegration": false,
        "sessionTimeout": 8
      }
    },
    "documents": {
      "folderHierarchy": {
        "maxDepth": 5,
        "defaultStructure": ["Department", "Project", "Category", "Year"],
        "folderTemplates": ["Standard", "Project-based", "Department-based"]
      },
      "namingConventions": {
        "autoGenerate": true,
        "mandatoryFields": ["title", "department", "date"],
        "pattern": "{department}_{title}_{date}"
      },
      "retention": {
        "enabled": true,
        "defaultDays": 2555,
        "archiveBeforeDelete": true
      },
      "versionControl": {
        "enabled": true,
        "maxVersions": 10,
        "autoVersioning": true
      }
    },
    "metadata": {
      "customFields": [
        {"name": "Department", "type": "dropdown", "required": true},
        {"name": "Priority", "type": "select", "required": false}
      ],
      "tagging": {
        "predefinedTags": ["urgent", "confidential", "public", "draft", "final"],
        "userGeneratedTags": true,
        "tagSuggestions": true
      },
      "classification": {
        "autoClassification": true,
        "rules": ["confidential-keywords", "department-based", "file-type"]
      }
    },
    "workflow": {
      "approvalFlows": {
        "enabled": true,
        "defaultFlow": "department-head-approval",
        "customFlows": ["legal-review", "finance-approval", "director-sign-off"]
      },
      "notifications": {
        "emailNotifications": true,
        "inAppNotifications": true,
        "uploadAlerts": true,
        "deadlineReminders": true
      },
      "automation": {
        "triggers": ["document-uploaded", "approval-completed", "deadline-reached"],
        "actions": ["move-to-folder", "send-notification", "create-task"]
      }
    },
    "upload": {
      "fileTypes": {
        "allowed": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "jpg", "png"],
        "blocked": ["exe", "bat", "cmd"]
      },
      "fileSizeLimit": 100,
      "quotas": {
        "perUser": 5000,
        "perGroup": 50000,
        "perProject": 100000
      },
      "storage": {
        "type": "local",
        "path": "/var/uploads/edms",
        "backupEnabled": true,
        "compressionEnabled": false
      }
    },
    "system": {
      "timezone": "Asia/Kuala_Lumpur",
      "backupSchedule": "daily",
      "logLevel": "info",
      "maintenanceMode": false,
      "autoUpdates": false,
      "systemMonitoring": true,
      "performanceMetrics": true
    }
  }
}
```

#### POST `/api/dms/settings`
Updates DMS settings with validation and automatic database creation.

**Request Body:** Complete or partial settings object
**Response:** Success confirmation with updated data

### Data Transformation
The API handles transformation between frontend structure and database format:
- **Arrays to Strings**: Converts arrays like `userRoles` to comma-separated strings for database storage
- **Nested Objects**: Flattens nested frontend structure to database columns
- **Type Conversion**: Handles boolean/integer conversions between frontend and database
- **Default Values**: Provides sensible defaults for undefined settings

## DMS Settings System

### Overview
The DMS Settings system provides comprehensive configuration management for all aspects of the document management system. Administrators can customize user access, document handling, metadata management, workflows, upload settings, and system configuration through an intuitive web interface.

### Settings Categories

#### 1. User & Access Management
- **User Roles**: Define custom roles (Admin, Editor, Viewer, Uploader, etc.)
- **RBAC Configuration**: Enable/disable role-based access control
- **User Groups**: Organize users into departments or teams
- **Permissions**: Granular control over view, edit, delete, download, and share permissions
- **Authentication**: SSO, MFA, and LDAP integration settings
- **Session Management**: Configure session timeout periods

#### 2. Document & Folder Settings
- **Folder Hierarchy**: Configure maximum depth and default structure
- **Naming Conventions**: Automatic name generation with customizable patterns
- **Document Retention**: Set retention policies and archive settings
- **Version Control**: Enable versioning with configurable version limits
- **Folder Templates**: Predefined folder structures for different use cases

#### 3. Metadata & Tagging
- **Custom Fields**: Define custom metadata fields with types (text, dropdown, date, etc.)
- **Tagging System**: Manage predefined tags and user-generated tags
- **Tag Suggestions**: Enable intelligent tag suggestions
- **Auto-Classification**: Configure automatic document classification rules

#### 4. Workflow & Automation
- **Approval Flows**: Configure document approval workflows
- **Notifications**: Email and in-app notification settings
- **Automation Triggers**: Define triggers for automated actions
- **Custom Workflows**: Create department-specific approval processes

#### 5. Upload & Storage Settings
- **File Type Restrictions**: Allowed and blocked file types
- **Size Limits**: Maximum file size and storage quotas
- **Storage Configuration**: Local storage or cloud storage settings
- **Backup Settings**: Automatic backup and compression options

#### 6. System Settings
- **Timezone Configuration**: System-wide timezone settings
- **Backup Schedules**: Automated backup frequency
- **Monitoring**: System monitoring and performance metrics
- **Maintenance Mode**: Enable/disable maintenance mode
- **Logging**: Configure system log levels

### Settings Interface Features

#### Tabbed Navigation
- **Organized Categories**: Six main categories with intuitive icons
- **Active Indicators**: Visual feedback for the current tab
- **Color-Coded Icons**: Each category has a distinct color scheme

#### Form Management
- **Real-time Updates**: Changes are reflected immediately in the UI
- **Validation**: Client-side and server-side validation
- **Loading States**: Visual feedback during save operations
- **Error Handling**: Comprehensive error messages with auto-dismiss

#### Dynamic Fields
- **Add/Remove Roles**: Dynamic management of user roles
- **Custom Field Builder**: Add/remove custom metadata fields with type selection
- **Array Management**: Tag lists and file type lists with comma-separated input

#### Import/Export Functionality
- **JSON Export**: Export complete settings as JSON for backup
- **JSON Import**: Import settings from backup files
- **Settings Migration**: Easy transfer between environments

#### Reset to Defaults
- **One-Click Reset**: Reset all settings to default values
- **Confirmation Dialog**: Prevent accidental resets
- **Selective Reset**: Reset individual categories (future enhancement)

### Implementation Details

#### Composable Pattern
```javascript
// useDmsSettings.js provides:
const {
  dmsSettings,           // Reactive settings object
  loading,               // Loading state
  saving,                // Saving state
  loadDmsSettings,       // Load from API
  updateDmsSettings,     // Save to API
  resetToDefaults,       // Reset functionality
  exportSettings,        // Export as JSON
  importSettings,        // Import from JSON
  getSetting,            // Get individual setting
  updateSetting          // Update individual setting
} = useDmsSettings();
```

#### Database Integration
- **Automatic Creation**: Settings table created automatically if not exists
- **Upsert Operations**: Update existing or create new settings
- **Default Values**: Sensible defaults for all configuration options
- **Data Transformation**: Automatic conversion between frontend and database formats

#### Error Handling
- **API Errors**: Graceful handling of network and server errors
- **Validation Errors**: Client-side validation with user-friendly messages
- **Fallback Values**: Default settings if API fails
- **Retry Mechanisms**: Automatic retry for failed operations

## Site Settings Integration

### Comprehensive Branding System
The site settings system allows complete customization of the application appearance:

#### Basic Configuration
- **Site Name**: Global application name with font size control
- **Site Description**: SEO and meta tag descriptions
- **Theme Selection**: Choose from standard and accessibility themes

#### Branding Assets
- **Site Logo**: Custom logo for header and sidebar
- **Loading Logo**: Branding for loading screens
- **Favicon**: Custom browser icon
- **Login Logo**: Dedicated login page branding

#### Advanced Customization
- **Custom CSS**: Inject custom styles globally
- **Custom Themes**: Upload and manage custom theme files
- **Font Configuration**: Custom font selection and sources

#### SEO Integration
- **Meta Tags**: Complete SEO meta tag management
- **Open Graph**: Social media sharing optimization
- **Twitter Cards**: Twitter-specific meta tags
- **Analytics**: Google Analytics and Tag Manager integration

### Global Application Integration
Site settings are integrated throughout the application:
- **Header Component**: Dynamic logo and name display
- **Loading Screen**: Branded loading experience
- **Document Title**: Dynamic page titles
- **Theme System**: Synchronized theme selection

## Security & Authentication

### Authentication System

The EDMS implements a comprehensive authentication and authorization system using Authentik integration for identity management and a three-tier role-based access control model.

#### Authentik Integration

Authentik is used as the identity provider with the following implementation:

```javascript
// Authentication integration in stores/dms.js
async authenticateWithAuthentik(username, password) {
  // In production, this connects to the Authentik API
  // The implementation here is a placeholder for demonstration
  
  // Authenticate and receive user profile with role information
  // Returns user object with role (superadmin, admin, or user)
}
```

#### User Roles and Permissions

The system implements three core roles with distinct permission levels:

```javascript
// Role definitions in stores/dms.js
systemRoles: [
  { 
    id: 'superadmin', 
    name: 'Super Administrator', 
    description: 'Full system access with ability to manage all settings, users, and content',
    color: 'purple' 
  },
  { 
    id: 'admin', 
    name: 'Administrator', 
    description: 'Administrative access to manage content and some system settings',
    color: 'blue' 
  },
  { 
    id: 'user', 
    name: 'User', 
    description: 'Standard user access for viewing and interacting with content based on permissions',
    color: 'green' 
  }
]
```

Role-based permissions are implemented through the `getRbacPermissions` method:

```javascript
// RBAC permissions implementation
async getRbacPermissions(userId) {
  // In production, this fetches permissions from Authentik
  // Returns permission object with granular access controls
  
  return {
    roles: ['superadmin' | 'admin' | 'user'],
    permissions: {
      documents: { view, edit, delete, approve, reject, download },
      cabinets: { view, create, edit, delete },
      accessRequests: { approve, reject, viewAll },
      systemSettings: { manage },
      users: { manage },
      roles: { manage }
    }
  };
}
```

### Navigation Authorization

The navigation system enforces role-based access through meta tags:

```javascript
// Role-based navigation in navigation/index.js
{
  "title": "Admin Dashboard",
  "path": "/dms/admin-dashboard",
  "icon": "material-symbols:dashboard",
  "meta": {
    "auth": {
      "role": ["admin", "superadmin"]  // Only these roles can access
    }
  }
}
```

### Role Switching

For testing and administrative purposes, the system includes a role switching component:

```vue
// Role switching implementation in pages/dms/switch-roles.vue
<script setup>
// Component for switching between Superadmin, Admin, and User roles
// Preserves the original role for restoration
</script>
```

### Secure Storage

User credentials and sensitive information are handled securely:

1. **Token Storage**: JWT tokens stored in HTTP-only cookies
2. **Password Handling**: Passwords never stored in the browser
3. **Session Management**: Auto-logout after configurable inactivity period
4. **Credential Transmission**: All authentication requests over HTTPS

## Deployment

### Production Environment
```bash
# Build for production
npm run build

# Start production server
npm run start

# Environment configuration
NODE_ENV=production
DATABASE_URL="mysql://user:pass@host:port/db"
NUXT_SECRET_KEY="production-secret-key"
```

### Docker Deployment
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
```

### Database Migrations
```bash
# Apply schema changes
npx prisma db push

# Generate migration files
npx prisma migrate dev --name init

# Apply migrations in production
npx prisma migrate deploy
```

## Maintenance & Monitoring

### Database Maintenance
- **Backup Strategies**: Automated database backups
- **Performance Monitoring**: Query optimization and indexing
- **Data Retention**: Configurable document retention policies
- **Archive Management**: Automated archiving of old documents

### System Monitoring
- **Performance Metrics**: Configurable system monitoring
- **Error Tracking**: Comprehensive error logging
- **Audit Logs**: User activity and system event logging
- **Health Checks**: API endpoint health monitoring

### Update Management
- **Automated Updates**: Optional automatic system updates
- **Version Control**: Database schema versioning
- **Rollback Procedures**: Safe rollback mechanisms
- **Testing Procedures**: Comprehensive testing protocols

## Extension & Customization

### Custom Components
The Rs component system allows easy customization:
```vue
<template>
  <RsButton variant="custom" @click="handleClick">
    Custom Action
  </RsButton>
</template>
```

### API Extensions
Add custom API endpoints:
```javascript
// server/api/custom/endpoint.js
export default defineEventHandler(async (event) => {
  // Custom logic here
  return { message: "Custom API response" };
});
```

### Theme Customization
Create custom themes:
```css
html[data-theme="custom-theme"] {
  --color-primary: 255, 0, 0;
  --color-secondary: 0, 255, 0;
  /* Custom variables */
}
```

### Plugin Development
Extend functionality with Nuxt plugins:
```javascript
// plugins/custom-plugin.client.js
export default defineNuxtPlugin(() => {
  // Client-side plugin logic
});
```

### Settings Extensions
The DMS settings system is designed for extensibility:
- **Custom Setting Categories**: Add new configuration sections
- **Validation Rules**: Custom validation for settings
- **Setting Computed Properties**: Derived settings based on other values
- **Setting Watchers**: React to setting changes automatically

This technical guide provides comprehensive coverage of the EDMS system architecture, implementation details, and customization options. The system is designed for scalability, maintainability, and extensibility while providing a robust document management solution.