System Architecture

Umo Office Convert is a document conversion service built with Node.js and Express. It converts various office documents into formats supported by Umo Office Viewer. The system integrates MySQL to persist conversion task information, supports cross-origin access, and provides Swagger API documentation.

Architecture Components

• Application service: Express provides HTTP APIs.
• Routing layer: src/routes includes base routes, conversion routes, and OpenAPI documentation routes.
• Conversion engine: converts Office documents into formats supported by Umo Office Viewer.
• Database: MySQL stores conversion tasks (table: convert_tasks). You can replace it with another database. See: Database.
• Storage: supports local filesystem or network object storage.
• Configuration: configured via environment variables (.env). See: Environment Variables.
• Authentication & security: file size limits and MIME type validation. See: Security & Compliance.
• Documentation: Swagger API documentation (mounted at /openapi in non-production). See: API Documentation.
• Logging: the log directory is configured via the LOG_DIR environment variable (PM2 optional).

Main Data Flow

1. An uploaded document or a document provided via path/URL is stored under UPLOAD_DIR (if configured).
2. The service generates an ID for the task and writes it to the convert_tasks table (status transitions: uploaded → converted/failed).
3. The document conversion engine converts the document.
4. The result file is written under CONVERTED_DIR.
5. The service returns the file stream and includes metadata in response headers (such as X-Task-Id).
6. You can download the converted file or the original file via /convert/{taskId}.
7. If CONVERTED_WEBHOOK_URL is configured, callbacks will be sent at the corresponding stages with conversion information.

Key Paths and Modules

• src/index.mjs: application entry, middleware and route mounting
• src/routes/base.mjs: basic health route
• src/routes/convert.mjs: upload/convert/download and caching
• src/routes/openapi.mjs: Swagger UI
• src/utils/mysql.mjs: MySQL connection and table initialization
• src/utils/env.mjs: environment variable loading

Deployment Topology

• Single service instance (PM2 / container)
• External MySQL service (recommended)
• Mount persistent volumes: upload directory, converted file storage directory, and log storage directory

Performance & Scalability

• Use caching (based on file hash) to avoid duplicate conversions.
• Move storage to object storage (such as S3) to reduce disk IO pressure.
• Use Nginx proxying and rate-limiting strategies to protect the service.

Observability

• Standardized log directory (LOG_DIR) and PM2 log collection
• Record key exceptions

Security Highlights

• Limit upload file size (MAX_FILE_SIZE).
• Validate MIME type and file extension consistency.
• Handle paths and URLs to avoid directory traversal and SSRF risks.