# nextcloud/files_retention architecture

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

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

## Overview

Files Retention is a Nextcloud app for rules that automatically delete tagged files after a configured age, optionally notifying the owner a day beforehand. An administrator configures rules in the Vue settings UI; its API requests create, list, or delete rules. The backend persists rules and schedules daily jobs, which find tagged files, compare their creation or modification time with the retention threshold, and delete expired files or issue notifications. The README and sampled source establish this main flow; unsampled settings and notification implementation are represented only where the tree supports their paths.

Main entry points: [`lib/BackgroundJob/RetentionJob.php`](https://github.com/nextcloud/files_retention/blob/master/lib/BackgroundJob/RetentionJob.php) (Daily retention job), [`lib/Service/RetentionService.php`](https://github.com/nextcloud/files_retention/blob/master/lib/Service/RetentionService.php) (Retention service), [`lib/EventListener.php`](https://github.com/nextcloud/files_retention/blob/master/lib/EventListener.php) (Event listener), [`src/AdminSettings.vue`](https://github.com/nextcloud/files_retention/blob/master/src/AdminSettings.vue) (Settings UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin settings"]
  node_admin_ui["Settings UI<br/>[AdminSettings.vue]"]
  node_ui_entry["Vue entry<br/>[main.js]"]
  node_store["Vuex store<br/>[index.js]"]
  node_retention_store["Rule state<br/>[retentionStore.js]"]
  node_frontend_api["API client"]
  node_admin_settings["Notification setting<br/>[Admin.php]"]
end

subgraph group_rules["Rule management"]
  node_routes["OCS routes<br/>[routes.php]"]
  node_api_controller["API controller<br/>[APIController.php]"]
  node_service["Retention service"]
  node_rule_db[("Rule database")]
end

subgraph group_execution["Retention execution"]
  node_retention_job["Daily retention job<br/>[RetentionJob.php]"]
  node_tag_mapper["Tagged file lookup"]
  node_mount_cache["Mount cache"]
  node_file_system["Nextcloud files"]
  node_file_nodes[("User files")]
end

subgraph group_integration["Nextcloud integration"]
  node_tag_manager["System tags"]
  node_job_list["Job scheduler"]
  node_config[("App configuration")]
  node_notification_manager["Notification service"]
  node_notifier["Notifier<br/>[Notifier.php]"]
  node_event_listener["Event listener<br/>[EventListener.php]"]
  node_event_sources["Rule and tag events"]
  node_application["App registration<br/>[Application.php]"]
end

node_admin_actor(("Administrator"))

node_admin_actor -->|"configures"| node_admin_ui
node_ui_entry -->|"mounts"| node_admin_ui
node_ui_entry -->|"installs"| node_store
node_admin_ui -->|"dispatches"| node_retention_store
node_retention_store -->|"requests rules"| node_frontend_api
node_frontend_api -->|"calls OCS"| node_routes
node_routes -->|"dispatches"| node_api_controller
node_api_controller -->|"invokes"| node_service
node_service -->|"reads/writes"| node_rule_db
node_service -->|"validates tags"| node_tag_manager
node_service -->|"schedules/removes"| node_job_list
node_job_list -->|"dispatches"| node_retention_job
node_retention_job -->|"reads rules"| node_rule_db
node_retention_job -->|"validates tag"| node_tag_manager
node_retention_job -->|"finds tagged files"| node_tag_mapper
node_retention_job -->|"finds mounts"| node_mount_cache
node_retention_job -->|"resolves nodes"| node_file_system
node_file_system -->|"accesses"| node_file_nodes
node_retention_job -->|"deletes expired files"| node_file_nodes
node_retention_job -->|"reads preference"| node_config
node_admin_settings -->|"stores preference"| node_config
node_retention_job -->|"sends notices"| node_notification_manager
node_notification_manager -.->|"delegates rendering"| node_notifier
node_application -->|"registers"| node_event_listener
node_application -->|"registers"| node_notifier
node_event_sources -->|"dispatches"| node_event_listener
node_event_listener -->|"handles rule events"| node_service
node_event_listener -->|"removes deleted-tag rules"| node_rule_db

click node_admin_ui "https://github.com/nextcloud/files_retention/blob/master/src/AdminSettings.vue"
click node_ui_entry "https://github.com/nextcloud/files_retention/blob/master/src/main.js"
click node_store "https://github.com/nextcloud/files_retention/blob/master/src/store/index.js"
click node_retention_store "https://github.com/nextcloud/files_retention/blob/master/src/store/retentionStore.js"
click node_frontend_api "https://github.com/nextcloud/files_retention/blob/master/src/services/retentionService.js"
click node_routes "https://github.com/nextcloud/files_retention/blob/master/appinfo/routes.php"
click node_api_controller "https://github.com/nextcloud/files_retention/blob/master/lib/Controller/APIController.php"
click node_service "https://github.com/nextcloud/files_retention/blob/master/lib/Service/RetentionService.php"
click node_retention_job "https://github.com/nextcloud/files_retention/blob/master/lib/BackgroundJob/RetentionJob.php"
click node_admin_settings "https://github.com/nextcloud/files_retention/blob/master/lib/Settings/Admin.php"
click node_notifier "https://github.com/nextcloud/files_retention/blob/master/lib/Notification/Notifier.php"
click node_event_listener "https://github.com/nextcloud/files_retention/blob/master/lib/EventListener.php"
click node_event_sources "https://github.com/nextcloud/files_retention/tree/master/lib/Event"
click node_application "https://github.com/nextcloud/files_retention/blob/master/lib/AppInfo/Application.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_admin_ui,node_ui_entry,node_store,node_retention_store,node_frontend_api,node_admin_settings toneBlue
class node_routes,node_api_controller,node_service,node_rule_db toneAmber
class node_retention_job,node_tag_mapper,node_mount_cache,node_file_system,node_file_nodes toneMint
class node_tag_manager,node_job_list,node_config,node_notification_manager,node_notifier,node_event_listener,node_event_sources,node_application toneRose
class node_admin_actor toneIndigo
```

## Components

### Admin settings

- [Settings UI](https://github.com/nextcloud/files_retention/blob/master/src/AdminSettings.vue): `src/AdminSettings.vue`
- [Vue entry](https://github.com/nextcloud/files_retention/blob/master/src/main.js): `src/main.js`
- [Vuex store](https://github.com/nextcloud/files_retention/blob/master/src/store/index.js): `src/store/index.js`
- [Rule state](https://github.com/nextcloud/files_retention/blob/master/src/store/retentionStore.js): `src/store/retentionStore.js`
- [API client](https://github.com/nextcloud/files_retention/blob/master/src/services/retentionService.js): `src/services/retentionService.js`
- [Notification setting](https://github.com/nextcloud/files_retention/blob/master/lib/Settings/Admin.php): `lib/Settings/Admin.php`

### Rule management

- [OCS routes](https://github.com/nextcloud/files_retention/blob/master/appinfo/routes.php): `appinfo/routes.php`
- [API controller](https://github.com/nextcloud/files_retention/blob/master/lib/Controller/APIController.php): `lib/Controller/APIController.php`
- [Retention service](https://github.com/nextcloud/files_retention/blob/master/lib/Service/RetentionService.php): `lib/Service/RetentionService.php`
- **Rule database**

### Retention execution

- [Daily retention job](https://github.com/nextcloud/files_retention/blob/master/lib/BackgroundJob/RetentionJob.php): `lib/BackgroundJob/RetentionJob.php`
- **Tagged file lookup**
- **Mount cache**
- **Nextcloud files**
- **User files**

### Nextcloud integration

- **System tags**
- **Job scheduler**
- **App configuration**
- **Notification service**
- [Notifier](https://github.com/nextcloud/files_retention/blob/master/lib/Notification/Notifier.php): `lib/Notification/Notifier.php`
- [Event listener](https://github.com/nextcloud/files_retention/blob/master/lib/EventListener.php): `lib/EventListener.php`
- [Rule and tag events](https://github.com/nextcloud/files_retention/tree/master/lib/Event): `lib/Event`
- [App registration](https://github.com/nextcloud/files_retention/blob/master/lib/AppInfo/Application.php): `lib/AppInfo/Application.php`

### Other components

- **Administrator**

## Connections

- Administrator → Settings UI: configures
- Vue entry → Settings UI: mounts
- Vue entry → Vuex store: installs
- Settings UI → Rule state: dispatches
- Rule state → API client: requests rules
- API client → OCS routes: calls OCS
- OCS routes → API controller: dispatches
- API controller → Retention service: invokes
- Retention service → Rule database: reads/writes
- Retention service → System tags: validates tags
- Retention service → Job scheduler: schedules/removes
- Job scheduler → Daily retention job: dispatches
- Daily retention job → Rule database: reads rules
- Daily retention job → System tags: validates tag
- Daily retention job → Tagged file lookup: finds tagged files
- Daily retention job → Mount cache: finds mounts
- Daily retention job → Nextcloud files: resolves nodes
- Nextcloud files → User files: accesses
- Daily retention job → User files: deletes expired files
- Daily retention job → App configuration: reads preference
- Notification setting → App configuration: stores preference
- Daily retention job → Notification service: sends notices
- Notification service → Notifier: delegates rendering
- App registration → Event listener: registers
- App registration → Notifier: registers
- Rule and tag events → Event listener: dispatches
- Event listener → Retention service: handles rule events
- Event listener → Rule database: removes deleted-tag rules