# nextcloud/officeonline architecture

> Architecture diagram of the GitHub repository nextcloud/officeonline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nextcloud/officeonline
- Repository: https://github.com/nextcloud/officeonline

## Overview

This project is a Nextcloud app that integrates Office Online Server into the Nextcloud ecosystem. The app provides the ability to view and edit Microsoft Office documents through an on-premise Office Online Server installation. The design combines PHP-based backend components (for handling WOPI requests, authentication, routing, and integration with Nextcloud) with JavaScript/Vue-based frontend components (for admin settings and possibly the document viewer).

##### Main components
- Nextcloud Application Layer – The integration points include the appinfo directory (which defines routes and server registration) and the Nextcloud hooks and middleware that enable the app to plug into Nextcloud.
- Backend Services (PHP):
– Controllers (in lib/Controller) handling document access, federation, settings, WOPI interactions, etc.
– WOPI and Database layer (in lib/Db and lib/WOPI) for document locking, mapping, and handling Office Online specific protocols.
– Service classes (lib/Service) that expose core functionalities like federation and capabilities.
– Migration scripts and configuration files (in lib/Migration, composer.json, etc.) that allow versioning and upgrading.
- Frontend Components (JavaScript/Vue):
– The src directory (especially src/admin.js, src/components, and src/view) contains Vue components and JavaScript that build the user interface (e.g., admin settings dashboard).
– CSS and assets (css, assets) provide styling and document/template resources.
- External Office Online Server:
– The Office Online Server is a separately deployed system (referenced in the README) that is trusted by Nextcloud through WOPI and used for document editing.
- Supporting Infrastructure:
– GitHub workflows and build configuration files for CI/CD (in .github/workflows, package.json, webpack.js, etc.) that handle linting, tests, and building the frontend assets.
– Internationalization support (the l10n directory) for multilingual UI support.
– Various testing frameworks (tests directory and behat tests), ensuring quality and regression testing.

##### Relationships and interactions
- The Nextcloud server (hosting the app) handles incoming user requests which are routed through the app’s routes (appinfo/routes.php) to the appropriate PHP Controllers.
- Controllers interact with the WOPI layer in the lib/WOPI directory to communicate document status and commands between Nextcloud and the external Office Online Server.
- The database abstraction (lib/Db) manages file locks, WOPI mappings, and related metadata.
- Frontend components (Vue and JavaScript in the src folder) initiate AJAX calls or other interactions with backend REST endpoints and update the UI based on user settings.
- External collaboration: The Office Online Server, which must be pre-deployed and configured, receives and processes document editing requests routed from the Nextcloud server.
- Integration points for updating capabilities or federated document access are managed by corresponding services in the lib/Service directory.
- Configuration, middleware, and hook listeners (in lib/Middleware, lib/Hooks, and lib/Listener) adjust security and auxiliary behaviors (e.g., content security policies, additional script loading).

##### Important architectural patterns
- Modular MVC-like separation: Controllers handle HTTP requests and delegate business logic to Service classes; views and admin panels are built separately.
- Middleware & Hook listeners: These ensure that requests are intercepted and processed correctly for security and integration (e.g., the WOPI middleware).
- Integration & Extensibility: The app integrates tightly with both Nextcloud’s plugin system and the Office Online platform using well-defined interfaces (WOPI protocol).
- Version migration: Migration scripts ensure that the app can evolve as Nextcloud and Office Online servers update.

##### Technologies and libraries
- PHP as the primary backend language with Nextcloud APIs.
- JavaScript/TypeScript and Vue.js for front-end components.
- Node.js/npm tooling for dependency management and building assets.
- Various linters and formatters (e.g., ESLint, Stylelint, PHP CS Fixer) configured through GitHub workflows to enforce code quality.
- Testing frameworks (PHPUnit, Behat) for automated testing.
- Internationalization files (JavaScript and JSON format) maintained in the l10n directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nextcloud Integration Layer
    subgraph "Nextcloud Integration Layer"
        A1["App Info (appinfo)"]:::integration
        A2["Application Registration (lib/AppInfo/Application.php)"]:::integration
    end
    A1 --> A2
    A2 -->|"routes"| B1

    %% Backend (PHP)
    subgraph "Backend (PHP)"
        B1["Controllers (lib/Controller)"]:::backend
        B2["WOPI Integration (lib/WOPI)"]:::backend
        B3["Database Layer (lib/Db)"]:::backend
        B4["Service Classes (lib/Service)"]:::backend
        B5["Migration & Config (lib/Migration, composer.json)"]:::backend
        B6["Middleware (lib/Middleware/WOPIMiddleware.php)"]:::backend
        B7["Hooks & Listeners (lib/Hooks & lib/Listener)"]:::backend
    end
    B1 -->|"WOPI_requests"| B2
    B2 -->|"DB_operations"| B3
    B1 -->|"Business_logic"| B4
    B4 -->|"Edit_commands"| D
    B1 -->|"Security_checks"| B6
    B6 -->|"Invoke_hooks"| B7
    B5 -.-> B1
    B5 -.-> B4

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        C1["Vue Components (src)"]:::frontend
        C2["CSS (css/)"]:::frontend
        C3["Assets (assets/)"]:::frontend
    end
    C1 -->|"API_calls"| B1

    %% External Integration
    subgraph "External Integration"
        D["Office Online Server"]:::external
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        E1["CI/CD & Build ('.github/workflows, package.json, webpack.js, etc)"]:::infra
        E2["Internationalization (l10n/)"]:::infra
        E3["Testing (tests/, src/tests/)"]:::infra
    end
    E1 --- A1
    E1 --- B1
    E1 --- C1
    E2 --- C1
    E3 --- B1

    %% Click Events
    click A1 "https://github.com/nextcloud/officeonline/tree/main/appinfo/"
    click A2 "https://github.com/nextcloud/officeonline/blob/main/lib/AppInfo/Application.php"
    click B1 "https://github.com/nextcloud/officeonline/tree/main/lib/Controller/"
    click B2 "https://github.com/nextcloud/officeonline/tree/main/lib/WOPI/"
    click B3 "https://github.com/nextcloud/officeonline/tree/main/lib/Db/"
    click B4 "https://github.com/nextcloud/officeonline/tree/main/lib/Service/"
    click B5 "https://github.com/nextcloud/officeonline/tree/main/lib/Migration/"
    click B6 "https://github.com/nextcloud/officeonline/blob/main/lib/Middleware/WOPIMiddleware.php"
    click B7 "https://github.com/nextcloud/officeonline/tree/main/lib/Hooks/"
    click C1 "https://github.com/nextcloud/officeonline/tree/main/src/"
    click C2 "https://github.com/nextcloud/officeonline/tree/main/css/"
    click C3 "https://github.com/nextcloud/officeonline/tree/main/assets/"
    click E1 "https://github.com/nextcloud/officeonline/tree/main/.github/workflows/"
    click E2 "https://github.com/nextcloud/officeonline/tree/main/l10n/"
    click E3 "https://github.com/nextcloud/officeonline/tree/main/tests/"

    %% Styles
    classDef integration fill:#FFCDD2,stroke:#000,stroke-width:2px;
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD180,stroke:#000,stroke-width:2px;
    classDef infra fill:#E1BEE7,stroke:#000,stroke-width:2px;
```
