# oca/knowledge architecture

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

- Interactive diagram: https://gitdiagram.com/oca/knowledge
- Repository: https://github.com/oca/knowledge

## Overview

This repository is an Odoo add-ons collection centered on document and knowledge management. The architecture is modular: each top-level package is a separate Odoo addon with its own `__manifest__.py`, Python models, XML views, security rules, translations, tests, and static assets. The shared runtime is the Odoo 18 server; there is no separate backend service.

1. Core domain model: `document_page`
This is the main knowledge-base subsystem. It defines the `document.page` model and related history/category/report/wizard logic, plus kanban UI customizations. It is the foundation that other addons extend. The main data flow is user edits in Odoo views and wizards → ORM writes to `document.page` / history records → rendered views, reports, and search/display logic.

2. Knowledge workspace and access scaffolding: `document_knowledge`
This addon provides a knowledge-oriented entry point around attachments and pages. It includes configuration models, access/security XML, demo data, and view definitions. It acts as a higher-level feature layer over Odoo documents/attachments, rather than introducing a new standalone service.

3. Page access and authorization variants
Several addons customize who can read/write pages:
- `document_page_access_group` and `document_page_access_group_user_role` add group-based access behavior.
- `document_page_group` defines access groups on pages.
- `document_page_approval` adds approval workflow semantics and mail template/data.
These modules primarily change security boundaries and page lifecycle, not the core content model.

4. Page metadata and classification
`document_page_tag` adds tags/keywords for lookup. `document_page_reference` adds page references and includes a small frontend editor asset plus a migration. These are enrichment layers on top of `document.page`, enabling discovery and cross-linking.

5. Linking pages to business objects
Several addons attach document pages to existing Odoo business models:
- `document_page_partner` links pages to partners.
- `document_page_product` links pages to products.
- `document_page_project` links pages to projects.
- `document_page_project_task` links pages to tasks.
This architecture is important: pages are not isolated documents; they become contextual documentation attached to operational records through ORM model extensions and form/view inheritance.

6. Attachment handling subsystems
There are three attachment-focused addons:
- `attachment_preview` adds preview support for attachments.
- `attachment_zipped_download` lets users download attachments as a ZIP; it includes a controller for HTTP download flow and model extensions to the attachment action.
- `document_url` turns an attachment-like record into a URL-backed attachment, with a wizard, XML views, SCSS, and frontend widget.
These modules sit at the boundary between Odoo’s attachment model (`ir.attachment`) and the client/UI, modifying how binaries are viewed, downloaded, or represented.

7. Frontend/UI layer
Frontend code is concentrated under each addon’s `static/src`. The repo uses Odoo’s modern JS module format (`*.esm.js`) plus XML templates and SCSS. Notable UI customizations include:
- `attachment_preview` integrating ViewerJS and custom web view/mail patches.
- `document_page` kanban controller/view overrides.
- `document_url` URL widget/template.
These assets are loaded by Odoo’s web client and alter user interaction without changing the deployment topology.

8. External/embedded client library usage
`attachment_preview` vendors ViewerJS under `static/lib/ViewerJS`. That library is embedded in the addon and used client-side for document rendering/preview, including PDF-related viewer assets. This is a packaged frontend dependency, not a remote service.

9. Server-side extension points
Most behavior is implemented through ORM model inheritance, view inheritance, and occasional controllers/wizards/hooks:
- Models extend `ir.attachment`, `document.page`, `project.*`, `product.*`, etc.
- Wizards handle actions like creating menus or showing diffs.
- `attachment_zipped_download` adds an HTTP controller.
- `document_page_approval` includes hooks and mail template data.
The repo’s architecture is thus “Odoo extension by composition”: model mixins and inherited views are the primary integration mechanism.

10. Security and configuration boundaries
Security is explicit per addon through `security/*.xml` and `ir.model.access.csv`. Some addons also ship configuration views/models (`document_knowledge`, `document_knowledge/res_config.py`). This means access control is part of the module boundary, not centralized in one shared security layer.

11. Localization and packaging
Every addon has `i18n/*.po` catalogs, making translation a first-class part of the UI architecture. `pyproject.toml`, lint configs, and GitHub workflows show this repo is packaged as a maintained OCA addon suite with automated checks, but those do not affect runtime behavior.

12. Test surface
Each functional module has its own tests under `tests/`, often covering model behavior, security, wizards, and view-related flows. The test layout mirrors the module boundaries, which is useful for understanding where each feature’s responsibility starts and ends.

Overall shape for a diagram: Odoo server at the center, with `document_page` as the core domain, attachment-related addons on one side, business-object link addons around it, and UI/assets/security as cross-cutting layers. The main data objects are `document.page`, `ir.attachment`, and linked business records like partners, products, projects, and tasks.

Main entry points: [`document_page`](https://github.com/oca/knowledge/tree/18.0/document_page) (Document page), [`document_knowledge`](https://github.com/oca/knowledge/tree/18.0/document_knowledge) (Knowledge entry), [`attachment_preview`](https://github.com/oca/knowledge/tree/18.0/attachment_preview) (Attachment preview), [`document_page_access_group`](https://github.com/oca/knowledge/tree/18.0/document_page_access_group) (Access groups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Odoo runtime"]
  node_odoo_server[("Odoo server<br/>runtime")]
end

subgraph group_core["Core pages"]
  node_document_page["Document page<br/>addon"]
  node_document_page_model["Page model<br/>orm model<br/>[document_page.py]"]
  node_document_page_history["Page history<br/>history model"]
  node_document_page_wizards["Page wizards<br/>wizard actions"]
  node_document_page_ui["Page UI<br/>web client assets"]
  node_document_knowledge["Knowledge entry<br/>addon"]
  node_knowledge_config["Knowledge config<br/>config model<br/>[res_config.py]"]
end

subgraph group_access["Access & workflow"]
  node_page_access_group["Access groups<br/>access addon"]
  node_page_access_role["Role access<br/>access addon"]
  node_page_group["Page groups<br/>access addon"]
  node_page_approval["Approval flow<br/>workflow addon"]
end

subgraph group_linking["Metadata & links"]
  node_page_tags["Page tags<br/>classification addon"]
  node_page_reference["Page refs<br/>enrichment addon"]
  node_page_partner["Partner pages<br/>linking addon"]
  node_page_product["Product pages<br/>linking addon"]
  node_page_project["Project pages<br/>linking addon"]
  node_page_task["Task pages<br/>linking addon"]
end

subgraph group_attachments["Attachment tools"]
  node_attachment_preview["Attachment preview<br/>attachment addon"]
  node_attachment_zip["ZIP download<br/>attachment addon"]
  node_document_url["URL attachments<br/>attachment addon"]
end

node_odoo_server -->|"loads"| node_document_page
node_odoo_server -->|"loads"| node_document_knowledge
node_odoo_server -->|"loads"| node_page_access_group
node_odoo_server -->|"loads"| node_attachment_preview
node_document_page -->|"defines"| node_document_page_model
node_document_page -->|"tracks"| node_document_page_history
node_document_page -->|"uses"| node_document_page_wizards
node_document_page -->|"renders"| node_document_page_ui
node_document_page -->|"extends by"| node_page_tags
node_document_page -->|"extends by"| node_page_reference
node_document_page -->|"extends by"| node_page_group
node_document_page -->|"extends by"| node_page_approval
node_document_page -->|"extends by"| node_page_partner
node_document_page -->|"extends by"| node_page_product
node_document_page -->|"extends by"| node_page_project
node_document_page -->|"extends by"| node_page_task
node_document_knowledge -->|"configures"| node_knowledge_config
node_document_knowledge -->|"orchestrates"| node_document_page
node_document_knowledge -->|"complements"| node_attachment_preview
node_page_access_group -->|"variant"| node_page_access_role
node_page_access_group -->|"coordinates"| node_page_group
node_page_approval -->|"records"| node_document_page_history
node_page_reference -->|"adds UI"| node_document_page_ui
node_attachment_preview -->|"shares boundary"| node_attachment_zip
node_attachment_preview -->|"shares boundary"| node_document_url
node_attachment_zip -->|"coordinates"| node_document_url
node_document_url -->|"integrates with"| node_document_page_model

click node_document_page "https://github.com/oca/knowledge/tree/18.0/document_page"
click node_document_page_model "https://github.com/oca/knowledge/blob/18.0/document_page/models/document_page.py"
click node_document_page_history "https://github.com/oca/knowledge/blob/18.0/document_page/models/document_page_history.py"
click node_document_page_wizards "https://github.com/oca/knowledge/tree/18.0/document_page/wizard"
click node_document_page_ui "https://github.com/oca/knowledge/tree/18.0/document_page/static/src"
click node_document_knowledge "https://github.com/oca/knowledge/tree/18.0/document_knowledge"
click node_knowledge_config "https://github.com/oca/knowledge/blob/18.0/document_knowledge/models/res_config.py"
click node_page_access_group "https://github.com/oca/knowledge/tree/18.0/document_page_access_group"
click node_page_access_role "https://github.com/oca/knowledge/tree/18.0/document_page_access_group_user_role"
click node_page_group "https://github.com/oca/knowledge/tree/18.0/document_page_group"
click node_page_approval "https://github.com/oca/knowledge/tree/18.0/document_page_approval"
click node_page_tags "https://github.com/oca/knowledge/tree/18.0/document_page_tag"
click node_page_reference "https://github.com/oca/knowledge/tree/18.0/document_page_reference"
click node_page_partner "https://github.com/oca/knowledge/tree/18.0/document_page_partner"
click node_page_product "https://github.com/oca/knowledge/tree/18.0/document_page_product"
click node_page_project "https://github.com/oca/knowledge/tree/18.0/document_page_project"
click node_page_task "https://github.com/oca/knowledge/tree/18.0/document_page_project_task"
click node_attachment_preview "https://github.com/oca/knowledge/tree/18.0/attachment_preview"
click node_attachment_zip "https://github.com/oca/knowledge/tree/18.0/attachment_zipped_download"
click node_document_url "https://github.com/oca/knowledge/tree/18.0/document_url"

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_odoo_server toneBlue
class node_document_page,node_document_page_model,node_document_page_history,node_document_page_wizards,node_document_page_ui,node_document_knowledge,node_knowledge_config toneAmber
class node_page_access_group,node_page_access_role,node_page_group,node_page_approval toneMint
class node_page_tags,node_page_reference,node_page_partner,node_page_product,node_page_project,node_page_task toneRose
class node_attachment_preview,node_attachment_zip,node_document_url toneIndigo
```

## Components

### Odoo runtime

Shared Odoo 18 server runtime and web client

- **Odoo server**: runtime · Shared Odoo 18 application server and ORM runtime

### Core pages

Main knowledge-page domain and its UI

- [Document page](https://github.com/oca/knowledge/tree/18.0/document_page): addon · Core document.page domain, history, reports, wizards, and kanban UI · `document_page`
- [Page model](https://github.com/oca/knowledge/blob/18.0/document_page/models/document_page.py): orm model · Defines document.page and related page behavior · `document_page/models/document_page.py`
- [Page history](https://github.com/oca/knowledge/blob/18.0/document_page/models/document_page_history.py): history model · Tracks page revisions and diff-related state · `document_page/models/document_page_history.py`
- [Page wizards](https://github.com/oca/knowledge/tree/18.0/document_page/wizard): wizard actions · Menu creation and show-diff flows · `document_page/wizard`
- [Page UI](https://github.com/oca/knowledge/tree/18.0/document_page/static/src): web client assets · Kanban controller/view overrides and styling · `document_page/static/src`
- [Knowledge entry](https://github.com/oca/knowledge/tree/18.0/document_knowledge): addon · Knowledge-oriented entry layer around attachments and pages · `document_knowledge`
- [Knowledge config](https://github.com/oca/knowledge/blob/18.0/document_knowledge/models/res_config.py): config model · Configuration models and settings views for the knowledge workspace · `document_knowledge/models/res_config.py`

### Access & workflow

Module variants that shape page visibility and approval

- [Access groups](https://github.com/oca/knowledge/tree/18.0/document_page_access_group): access addon · Group-based page access rules and page extensions · `document_page_access_group`
- [Role access](https://github.com/oca/knowledge/tree/18.0/document_page_access_group_user_role): access addon · User-role variant for page access control · `document_page_access_group_user_role`
- [Page groups](https://github.com/oca/knowledge/tree/18.0/document_page_group): access addon · Defines access groups on pages · `document_page_group`
- [Approval flow](https://github.com/oca/knowledge/tree/18.0/document_page_approval): workflow addon · Adds approval semantics, mail template data, and hooks · `document_page_approval`

### Metadata & links

Classification and attachments to business objects

- [Page tags](https://github.com/oca/knowledge/tree/18.0/document_page_tag): classification addon · Adds tags and keywords for lookup and filtering · `document_page_tag`
- [Page refs](https://github.com/oca/knowledge/tree/18.0/document_page_reference): enrichment addon · Adds page references and editor-side reference support · `document_page_reference`
- [Partner pages](https://github.com/oca/knowledge/tree/18.0/document_page_partner): linking addon · Links pages to partners · `document_page_partner`
- [Product pages](https://github.com/oca/knowledge/tree/18.0/document_page_product): linking addon · Links pages to products and template records · `document_page_product`
- [Project pages](https://github.com/oca/knowledge/tree/18.0/document_page_project): linking addon · Links pages to projects · `document_page_project`
- [Task pages](https://github.com/oca/knowledge/tree/18.0/document_page_project_task): linking addon · Links pages to tasks · `document_page_project_task`

### Attachment tools

Modules that change attachment preview, download, and URL behavior

- [Attachment preview](https://github.com/oca/knowledge/tree/18.0/attachment_preview): attachment addon · Preview support for binaries and ViewerJS-based rendering · `attachment_preview`
- [ZIP download](https://github.com/oca/knowledge/tree/18.0/attachment_zipped_download): attachment addon · Downloads attachments as ZIP and adds HTTP controller flow · `attachment_zipped_download`
- [URL attachments](https://github.com/oca/knowledge/tree/18.0/document_url): attachment addon · Represents attachment-like records backed by URLs with wizard and widget · `document_url`

## Connections

- Odoo server → Document page: loads · Odoo installs the addon and its ORM/UI extensions
- Odoo server → Knowledge entry: loads · Workspace entry addon runs inside Odoo
- Odoo server → Access groups: loads · Access rules are applied by the Odoo runtime
- Odoo server → Attachment preview: loads · Attachment behavior is extended in the web client and ORM
- Document page → Page model: defines · Core page model implementation
- Document page → Page history: tracks · Revision and diff history for pages
- Document page → Page wizards: uses · Wizard flows act on page records
- Document page → Page UI: renders · Kanban and styling customizations
- Document page → Page tags: extends by · Tag model and lookup enrichment build on the core page model
- Document page → Page refs: extends by · Reference links and editor support build on the core page model
- Document page → Page groups: extends by · Access-group semantics attach to pages
- Document page → Approval flow: extends by · Approval workflow and history logic layer onto pages
- Document page → Partner pages: extends by · Pages are linked to partner records
- Document page → Product pages: extends by · Pages are linked to products and templates
- Document page → Project pages: extends by · Pages are linked to projects
- Document page → Task pages: extends by · Pages are linked to project tasks
- Knowledge entry → Knowledge config: configures · Settings and access scaffolding for the knowledge workspace
- Knowledge entry → Document page: orchestrates · Provides a higher-level entry around page knowledge management
- Knowledge entry → Attachment preview: complements · Knowledge workspace relies on richer attachment handling
- Access groups → Role access: variant · User-role extension of group-based page access
- Access groups → Page groups: coordinates · Both modules shape page visibility boundaries
- Approval flow → Page history: records · Approval state is tied to page lifecycle/history
- Page refs → Page UI: adds UI · Editor asset enhances reference entry and rendering
- Attachment preview → ZIP download: shares boundary · Both modify attachment actions and user flows
- Attachment preview → URL attachments: shares boundary · Both are client-side attachment experience extensions
- ZIP download → URL attachments: coordinates · Attachment record handling is extended in different ways
- URL attachments → Page model: integrates with · URL-backed records participate in the document ecosystem