Document Reference Storage

Summary

Source-backed persistence of the AssetDocumentReference child entity — metadata rows that reference externally-owned document content held by the Document Service. This database stores only the pointer and descriptive metadata; it never stores the file bytes.

Audience

Backend engineers, database reviewers, architects, QA, support, operations, security reviewers, and product owners.

Overview

AssetDocumentReference is an aggregate child owned by the Asset aggregate root and maps to the AssetDocumentReferences table. Each row describes one document attached to an asset (for example an invoice, warranty, handover form, return form, damage report, or asset photo) and records where the actual content lives in the Document Service. The binary content itself is never persisted here — only the reference and its metadata.

Confirmed persistence behavior

Field	Storage	Required	Notes
Id	Guid primary key (ValueGeneratedNever)	Yes	App-assigned so nav-added rows insert cleanly
TenantId	integer	Yes	Tenant scope; participates in query filter and composite index
AssetId	Guid foreign key	Yes	References the parent Assets row (cascade delete)
DocumentType	varchar(80)	Yes	Free-form classification
FileName	varchar(400)	Yes	Descriptive file name
ContentType	varchar(160)	No	MIME type
StorageObjectKey	varchar(500)	Yes	Storage locator string
DocumentServiceId	Guid	No	External Document Service document identifier; null indicates a metadata-only fallback
StorageObjectId	Guid	No	External physical blob identifier
SizeBytes	bigint	Yes	Reported size
Sha256	varchar(128)	No	Content hash when supplied
UploadedBy	varchar(256)	Yes	Uploader identity string
UploadedOnUtc	timestamptz	Yes	Upload timestamp

• Parent ownership: rows are children of the Asset aggregate, configured HasMany documents WithOne with HasForeignKey(AssetId) and OnDelete(Cascade). One asset has zero-or-many document references (1..*).
• External identifiers: DocumentServiceId and StorageObjectId are nullable Guid references that point at content owned by the Document Service. They are identifier-only values with no foreign key to any other service.
• Bytes owned externally: the file bytes are never stored in this database. Only the reference row and its metadata live here; the content is owned by the Document Service.
• HasStoredContent: a computed indicator derived from whether the external document identifier is present; it is not a persisted column.
• Delete semantics: removing a document (RemoveDocument) deletes only the reference row. The external blob is retained in the Document Service; no delete call is made against it.
• No lifecycle governance of external content: there is no versioning, retention, cleanup, or reconciliation of the external document from this service.
• Tenant filter: yes — the global query filter applies to this entity.

Indexes

• IX_AssetDocumentReferences_AssetId — convention-generated single-column index on the foreign key.
• IX_AssetDocuments_Tenant_Asset — composite index on (TenantId, AssetId).

Classification

Implemented reference-only aggregate-child persistence with externally-owned content.

Requires confirmation

Whether external-document versioning, retention, or reference-to-blob reconciliation is required is not decided in source and requires confirmation.

Diagram

Related Articles

• Asset database documentation
• Asset Storage

See Also

• Assignment History Storage
• Workflow Reference Storage

Keywords

• Document reference
• Document Reference Storage
• Draft database documentation

Source References

• microservices/src/asset-service/Domain/Asset/Asset.cs
• microservices/src/asset-service/Infrastructure/AssetDbContext.cs
• microservices/src/asset-service/Application/Commands/DocumentCommands.cs
• microservices/src/asset-service/Infrastructure/AssetDocumentGateway.cs

Revision Information

• Status: Draft
• Last reviewed: 2026-07-17
• Review cycle: Quarterly