ONLYOFFICE Nextcloud Integration — Repository Analysis

1. What Is This Project?

This is a Nextcloud app that integrates ONLYOFFICE Docs (a self-hosted Document Server) with Nextcloud. It enables:

In-browser editing of documents, spreadsheets, and presentations (DOCX, XLSX, PPTX, PDF, and 50+ formats)
Real-time co-editing — multiple users editing simultaneously
Version history — track and restore document revisions
Template management — create documents from templates
Federated editing — co-edit across linked Nextcloud instances
Format conversion — convert between office formats server-side

Key facts:

App ID: onlyoffice
Version: 10.0.0 (requires Nextcloud 33)
License: AGPL-3.0
Author: Ascensio System SIA
Language split: ~60% PHP backend, ~40% JavaScript frontend

2. Top-Level Directory Structure

onlyoffice-nextcloud/
├── appinfo/             # Nextcloud app metadata & routing
│   ├── info.xml         # App ID, version, dependencies, settings registration
│   └── routes.php       # All HTTP routes (web + OCS API)
│
├── lib/                 # PHP backend (~46 files)
│   ├── AppInfo/         # App bootstrap
│   ├── Controller/      # 8 controllers (editor, callback, settings, API)
│   ├── Listeners/       # 8 event listeners (file actions, CSP, sharing)
│   ├── Cron/            # Background jobs
│   ├── Command/         # CLI commands
│   ├── Migration/       # Database migrations
│   ├── AppConfig.php    # Central config (1,200+ lines)
│   ├── Crypt.php        # JWT token handling
│   ├── DocumentService.php  # Document Server connector
│   ├── FileUtility.php  # File operations
│   ├── KeyManager.php   # Document key storage
│   └── ...              # Template, preview, notification managers
│
├── src/                 # JavaScript frontend (~31 files)
│   ├── main.js          # Files app integration (context menus, file actions)
│   ├── editor.js        # Main editor interface
│   ├── settings.js      # Admin settings page
│   ├── share.js         # Sharing panel
│   ├── viewer.js        # Read-only viewer
│   ├── template.js      # Template picker
│   ├── desktop.js       # Desktop client integration
│   ├── directeditor.js  # Direct editing (token-based)
│   └── listener.js      # Editor event listener
│
├── templates/           # PHP templates (8 files)
│   ├── editor.php       # Editor page (loads iframe)
│   ├── settings.php     # Admin settings form
│   └── ...              # Share, loader, picker templates
│
├── css/                 # Stylesheets (7 files)
├── img/                 # Icons — app logo, format icons (DOCX, XLSX, PPTX, PDF)
├── l10n/                # Localization — 20+ languages (JSON + JS)
├── assets/              # Static assets
├── screenshots/         # Documentation screenshots
├── licenses/            # License info
├── vendor/              # Composer dependencies (firebase/php-jwt)
│
├── .github/             # CI/CD workflows (lint, build, release)
├── composer.json        # PHP dependencies
├── package.json         # JS dependencies & build scripts
├── webpack.js           # Webpack entry points config
└── Makefile             # Build automation

3. How It Works — The Big Picture

┌─────────────────────────────────────────────────────────┐
│  User's Browser                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │  Nextcloud Files UI                             │    │
│  │  (main.js adds "Edit in ONLYOFFICE" actions)    │    │
│  └──────────────────┬──────────────────────────────┘    │
│                     │ click                              │
│  ┌──────────────────▼──────────────────────────────┐    │
│  │  Editor Page (editor.php + editor.js)           │    │
│  │  ┌──────────────────────────────────────┐       │    │
│  │  │  ONLYOFFICE Document Editor iframe   │       │    │
│  │  │  (loaded from Document Server)       │       │    │
│  │  └──────────────────┬───────────────────┘       │    │
│  └─────────────────────┼───────────────────────────┘    │
└────────────────────────┼────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌──────────────┐
│  Nextcloud   │  │  Document   │  │  Nextcloud    │
│  Backend     │  │  Server     │  │  Backend      │
│ (PHP app)    │  │ (ONLYOFFICE)│  │  Callback     │
│              │  │             │  │              │
│ GET config   │  │ Serves      │  │ POST /track  │
│ GET file URL │  │ editor UI   │  │ (save changes│
│ JWT token    │  │ Converts    │  │  on close)   │
│ generation   │  │ files       │  │              │
└─────────────┘  └─────────────┘  └──────────────┘

Document Editing Flow:

User clicks "Edit in ONLYOFFICE" — main.js triggers navigation
EditorController generates a JWT-signed config with document URL, permissions, user info
Editor page loads — iframe points to ONLYOFFICE Document Server with the config
Document Server fetches the file from Nextcloud via the download callback URL
User edits — changes are tracked in Document Server's memory
On close/save — Document Server POSTs the changed file back to CallbackController.track()
Nextcloud stores the updated file and creates a version entry

4. Backend Architecture (PHP)

4.1 Controllers (the API layer)

Controller	Routes	Purpose
EditorController	`/onlyoffice/{fileId}`, `/ajax/*`	Main editor — open files, save, convert, history, mentions, download
CallbackController	`/onlyoffice/track`, `/onlyoffice/download`	Document Server callbacks — receive changes, serve files
EditorApiController	`/api/v1/config/{fileId}`	OCS API — generate editor configuration with JWT
SettingsController	`/ajax/settings/*`	Admin settings — server address, security, common settings
TemplateController	`/ajax/template`, `/preview`	Template CRUD and preview
SharingApiController	`/api/v1/shares/{fileId}`	OCS API — file share management
FederationController	`/api/v1/key`, `/api/v1/keylock`, `/api/v1/healthcheck`	Federation key exchange and health
JobListController	background job management	Background job scheduling

4.2 Core Services

Class	Purpose
AppConfig.php	Central config store (~1,200 lines). Document Server URL, JWT settings, supported formats, watermarks, security, feature flags. This is the largest and most important config file.
DocumentService.php	Connector to Document Server API. Generates revision IDs, calls conversion endpoints, manages document info requests.
Crypt.php	JWT token generation/verification using HS256 via `firebase/php-jwt`. Every request between Nextcloud and Document Server is JWT-signed.
KeyManager.php	Manages document keys in DB table `onlyoffice_filekey`. Tracks locks, force-save status.
FileUtility.php	File system operations — get file info, MIME types, share management, permissions.
FileVersions.php	Version history — stores edit records, tracks who edited when.
TemplateManager.php	Template storage in `appdata_{instanceid}/onlyoffice/template`. CRUD for document templates.
ExtraPermissions.php	Extended permission system — integrates with Nextcloud Talk for comments/chat during co-editing.
RemoteInstance.php	Federated instance management — DB table `onlyoffice_instance`, health checks with 12-hour TTL cache.
Preview.php	Generates file preview images for Nextcloud's preview system.

4.3 Event Listeners

Listener	Event	Purpose
FilesListener	`LoadAdditionalScriptsEvent`	Injects `main.js` into the Files app, adds "New Document" menu items
DirectEditorListener	`RegisterDirectEditorEvent`	Registers ONLYOFFICE as a direct editor for supported formats
ViewerListener	`LoadViewer`	Loads editor in view-only mode
FileSharingListener	`BeforeTemplateRenderedEvent`	Adds sharing panel to editor
CreateFromTemplateListener	`FileCreatedFromTemplateEvent`	Handles new-file-from-template flow
ContentSecurityPolicyListener	`AddContentSecurityPolicyEvent`	Adds Document Server domain to CSP whitelist
WidgetListener	`HttpBeforeTemplateRenderedEvent`	Dashboard widget
DocumentUnsavedListener	custom event	Fires notifications for unsaved documents

4.4 Database Tables

Table	Columns	Purpose
`onlyoffice_filekey`	`file_id` (PK), `key`, `lock`, `fs`	Document identifiers, edit locks, force-save flags
`onlyoffice_instance`	`remote`, `expire`, `status`	Federated instance health tracking
`onlyoffice_extraperm`	share-based	Extended co-editing permissions

5. Frontend Architecture (JavaScript)

5.1 Webpack Entry Points

Entry	File	Purpose
`main`	`src/main.js`	Core integration — registers file actions ("Edit in ONLYOFFICE"), new-document menu items (DOCX/XLSX/PPTX/PDF), context menus in the Files app
`editor`	`src/editor.js`	Editor page — fetches config via AJAX, initializes ONLYOFFICE Document API iframe, manages editor lifecycle
`settings`	`src/settings.js`	Admin panel — Document Server URL, JWT secret, format toggles, watermarks, security
`share`	`src/share.js`	Sharing sidebar — share links, permissions for co-editing
`viewer`	`src/viewer.js`	Read-only viewer — opens documents in view mode
`template`	`src/template.js`	Template picker — select/create from templates
`desktop`	`src/desktop.js`	Desktop client — integration with Nextcloud desktop app
`directeditor`	`src/directeditor.js`	Direct editing — token-based editing without standard Files UI
`listener`	`src/listener.js`	Event bridge — handles editor close, save-as, image insertion, mail merge

5.2 Key Frontend Dependencies

Package	Purpose
`@nextcloud/files`	File actions API, new-file menu registration
`@nextcloud/auth`	Authentication tokens
`@nextcloud/initial-state`	Server → client state transfer (settings, config)
`@nextcloud/l10n`	Localization/translation
`@nextcloud/router`	URL generation for Nextcloud routes
`@nextcloud/sharing`	Sharing UI integration
`@nextcloud/event-bus`	Cross-component events
`vue@^2.7`	UI framework

6. Supported File Types

Editable

Category	Formats
Documents	DOCX, ODT, RTF, TXT, DOCXF (forms)
Spreadsheets	XLSX, ODS, CSV
Presentations	PPTX, ODP
PDFs	PDF (with form editing)

View-Only / Convertible

Category	Formats
Documents	EPUB, FB2, HTML, HWP, HWPX, Pages, MD
Spreadsheets	Numbers
Presentations	Keynote
Drawings	VSDX, VSSX, VSTX, ODG
Images	TIFF, SVG

7. Security Architecture

JWT Authentication

Algorithm: HS256 (HMAC SHA-256) via firebase/php-jwt
Every request between Nextcloud ↔ Document Server carries a JWT token
Configurable secret, expiry, and leeway (clock skew tolerance)

Content Security Policy

ContentSecurityPolicyListener dynamically adds the Document Server domain to Nextcloud's CSP
Required because the editor runs in an iframe from a different origin

File Locking

Database-tracked locks prevent conflicting edits
Automatic cleanup via EditorsCheck background job

Watermarks

Admin-configurable text, transparency, angle, color
Can be applied per user/group/share type

8. Configuration Options (Admin Settings)

Setting	Description
Document Server address	External URL for the ONLYOFFICE Docs server
Internal Server address	URL used for server-to-server communication (if different)
Storage address	URL the Document Server uses to reach Nextcloud
JWT Secret	Shared secret for token signing
JWT Expiry	Token lifetime
Editable formats	Which formats open in edit mode (vs. view)
Supported conversions	Which format conversions are available
Watermark settings	Text, transparency, angle, color
Same-tab editing	Open editor in same tab or new tab
Advanced sidebar	Show document info sidebar
Live view for shares	Allow live viewing of shared documents
Demo server	Use ONLYOFFICE demo server (for testing)

9. Build System

Build Commands

npm install          # Install JS dependencies
npm run build        # Production webpack build
npm run dev          # Development build with watch
composer install     # Install PHP dependencies (firebase/php-jwt)

CI/CD Workflows (`.github/workflows/`)

Workflow	Purpose
`lint-eslint.yml`	JavaScript linting
`lint-phpcs.yml`	PHP CodeSniffer
`lint-php.yml`	PHP syntax validation
`artifact.yml`	Build release artifacts
`release.yml`	Automated releases
`create-tag.yml`	Git tag creation

10. Common Contribution Areas

Easy / Good First Issues

Area	What To Do	Files
Translations	Add/improve translations for your language	`l10n/.json`, `l10n/.js`
CSS fixes	Fix styling issues, dark mode support	`css/*.css`
Format support	Add new file format icons or MIME mappings	`img/`, `lib/AppConfig.php`
Documentation	Improve README, add setup guides	`README.md`

Medium Complexity

Area	What To Do	Files
New file actions	Add context menu items in Files app	`src/main.js`
Settings UI	Add new admin settings options	`src/settings.js`, `templates/settings.php`, `lib/Controller/SettingsController.php`
Template improvements	Better template picker, categories	`src/template.js`, `lib/TemplateManager.php`
Sharing enhancements	Improve co-editing permission UI	`src/share.js`, `lib/ExtraPermissions.php`
Preview generation	Improve thumbnail quality/formats	`lib/Preview.php`

Advanced

Area	What To Do	Files
Editor configuration	Add new Document Server config options to the editor setup	`lib/Controller/EditorController.php`, `lib/Controller/EditorApiController.php`
Callback handling	Handle new Document Server callback events	`lib/Controller/CallbackController.php`
Federation	Improve cross-instance editing	`lib/RemoteInstance.php`, `lib/Controller/FederationController.php`
Performance	Optimize file locking, key management	`lib/KeyManager.php`, `lib/Cron/EditorsCheck.php`
Security	JWT improvements, CSP hardening	`lib/Crypt.php`, `lib/Listeners/ContentSecurityPolicyListener.php`
Version history	Improve diff/restore functionality	`lib/FileVersions.php`, editor history endpoints
Controller features	Add new API endpoints	`lib/Controller/`, `appinfo/routes.php`

Architecture Changes

Area	What To Do	Files
Vue 3 migration	Upgrade from Vue 2.7 to Vue 3	`src/`, `package.json`, `webpack.js`
TypeScript	Add type safety to frontend	`src/.js` → `src/.ts`
Database schema	New tables for features	`lib/Migration/`
New Nextcloud APIs	Adopt newer NC framework features	`lib/Listeners/`, `lib/AppInfo/Application.php`

11. Development Setup

Prerequisites

Nextcloud 33 instance (dev environment)
ONLYOFFICE Document Server (or use demo mode)
PHP 8.1+, Node.js 18+, npm

Quick Start

# Clone into Nextcloud apps directory
cd /path/to/nextcloud/apps
git clone https://github.com/xunema/onlyoffice-nextcloud.git onlyoffice

# Install dependencies
cd onlyoffice
composer install
npm install

# Build frontend
npm run build

# Enable app
cd /path/to/nextcloud
php occ app:enable onlyoffice

# Configure Document Server URL in Admin → ONLYOFFICE

Development Workflow

npm run dev          # Watch mode — rebuilds on file changes
# Edit PHP files — changes are immediate (no build needed)
# Edit JS/Vue files — webpack rebuilds automatically

12. Key Files to Read First

If you're new to this codebase, read these in order:

appinfo/info.xml — What this app is, what it requires
appinfo/routes.php — All URL routes (the API surface)
lib/AppConfig.php — Configuration options (largest file, central to everything)
lib/Controller/EditorController.php — Main editor logic (~1,500 lines)
lib/Controller/CallbackController.php — How Document Server communicates back (~1,000 lines)
src/main.js — How the app integrates into Nextcloud Files
src/editor.js — How the editor page works
templates/editor.php — The editor HTML template
lib/Crypt.php — JWT security
webpack.js — Frontend build configuration

ONLYOFFICE Nextcloud Integration — Repository Analysis

1. What Is This Project?

2. Top-Level Directory Structure

3. How It Works — The Big Picture

Document Editing Flow:

4. Backend Architecture (PHP)

4.1 Controllers (the API layer)

4.2 Core Services

4.3 Event Listeners

4.4 Database Tables

5. Frontend Architecture (JavaScript)

5.1 Webpack Entry Points

5.2 Key Frontend Dependencies

6. Supported File Types

Editable

View-Only / Convertible

7. Security Architecture

JWT Authentication

Content Security Policy

File Locking

Watermarks

8. Configuration Options (Admin Settings)

9. Build System

Build Commands

CI/CD Workflows (.github/workflows/)

10. Common Contribution Areas

Easy / Good First Issues

Medium Complexity

Advanced

Architecture Changes

11. Development Setup

Prerequisites

Quick Start

Development Workflow

12. Key Files to Read First

CI/CD Workflows (`.github/workflows/`)