Attachments, notes, and storage

Any record in Cluster ERP can carry files and notes through two shared tables in the core. This page lists the tables, services, and routes in core/attachments.py, core/notes.py, server/routes/attachments.py, and server/routes/notes.py, the upload policy in core/upload_policy.py, and the storage backends in core/storage.py. The versioned document management of the documents module is a separate feature; see documents.

Scope and source¶

• Defined in: src/cluster_erp/core/attachments.py (Attachment, AttachmentService), src/cluster_erp/core/notes.py (Note, NoteService), src/cluster_erp/core/upload_policy.py (check_upload), src/cluster_erp/core/storage.py (StorageBackend, create_storage_backend), src/cluster_erp/server/routes/attachments.py, src/cluster_erp/server/routes/notes.py
• Count: 8 attachment routes and 6 note routes (counted from the @router. decorators); 3 storage backend classes; 40 default allowed extensions

Both tables link to their parent record by entity_type and entity_id, with no foreign key, so any entity can use them.

Attachments¶

core_attachments derives from BaseModel and adds these columns (src/cluster_erp/core/attachments.py:51-63):

The storage key is attachments/<entity_type>/<entity_id>/<stored name>, prefixed with tenants/<tenant key>/ on a multi-tenant node (src/cluster_erp/core/attachments.py:38-48). Downloads carry a Content-Disposition header built by safe_content_disposition, which strips quote, backslash, line-break, and semicolon characters from the ASCII name and percent-encodes the UTF-8 name (src/cluster_erp/core/attachments.py:24-35).

AttachmentService methods (src/cluster_erp/core/attachments.py:88-206):

Attachment routes¶

The router prefix is /api/v1/attachments (src/cluster_erp/server/routes/attachments.py:27).

A download of a row whose file is missing answers FILE_NOT_FOUND_ON_DISK with HTTP 404 (src/cluster_erp/server/routes/attachments.py:114-115).

Upload policy¶

check_upload(filename, data, allowed) returns the accepted extension or raises AppError with code UPLOAD_TYPE_REFUSED and HTTP 415 (src/cluster_erp/core/upload_policy.py:65-84). It applies two checks:

1. The lower-case extension must be in the allow list: the setting attachment_allowed_extensions, or the 40 defaults in DEFAULT_ALLOWED_EXTENSIONS (src/cluster_erp/core/upload_policy.py:21-27, src/cluster_erp/config/settings.py:368-374).
2. For 24 extensions with a known file signature, the content must start with that signature (src/cluster_erp/core/upload_policy.py:30-55, src/cluster_erp/core/upload_policy.py:76-82).

The upload route calls check_upload with the configured list (src/cluster_erp/server/routes/attachments.py:73-75). The module docstring states that executables and scripts are not on the list (src/cluster_erp/core/upload_policy.py:1-10).

Notes¶

core_notes derives from BaseModel and adds code, entity_type, entity_id, and content (src/cluster_erp/core/notes.py:17-23). NoteCreate takes entity_type (at most 50 characters), entity_id, and a non-empty content; NoteUpdate takes content (src/cluster_erp/core/notes.py:26-33). NoteService lists, gets, creates (with a code from the note sequence), updates, deactivates, bulk-deactivates, and counts notes (src/cluster_erp/core/notes.py:48-114).

Note routes¶

The router prefix is /api/v1/notes (src/cluster_erp/server/routes/notes.py:14).

Storage backends¶

StorageBackend is a protocol with save, load, delete, and exists (src/cluster_erp/core/storage.py:11-18). The lifespan creates one backend per process and stores it on app.state.storage (src/cluster_erp/server/app.py:65-75, src/cluster_erp/server/app.py:92).

create_storage_backend picks S3 when storage_backend is s3, else local storage. It wraps the result in EncryptedStorageBackend when storage_encryption_key is set, and logs a warning when it is not (src/cluster_erp/core/storage.py:177-209). The settings validator requires the key in multi-tenant mode (src/cluster_erp/config/settings.py:805-809). Key handling is documented in second factor and secret storage.

Constraints and validation¶

• An attachment row and its file are written in the same request; the file is saved before the row is flushed (src/cluster_erp/core/attachments.py:126-142).
• Deactivating an attachment does not remove the stored file (src/cluster_erp/core/attachments.py:155-161). Removal of files at retention time belongs to the records module; see records.

Terms introduced¶

Related pages¶

• Platform core
• Shared server routes
• Settings reference
• Records, documents, viewer, and share

Verified against commit 92f8051 on 2026-11-13.