Treat evidence as a workflow spine
Evidence should not sit beside a private workflow as a drawer of attachments. It should be a durable, metadata-safe spine that connects intake, review, records, and handoff.
Yesterday's implementation work kept circling the same product rule from several angles: if a private workflow depends on supporting documents, the documents cannot remain an afterthought. Uploads, inbox review, record linking, detail pages, missing-evidence status, and reviewer handoff all need to share one durable evidence model.
The public lesson is not about one app or one register. It is about the boundary between private files and operational state. A file can be sensitive and temporary access to it should be tightly controlled. The evidence record around that file can still be durable, typed, versioned, linkable, and useful across the product.
Do not build an attachment drawer
The simplest document feature is an upload field. That is also where many private products get stuck. Files are uploaded, maybe a filename appears somewhere, and later the operator has to remember which file proves which transaction, decision, loan, approval, or exception.
A workflow spine starts differently. The product creates a document record as soon as evidence enters the system. That record stores safe metadata: document title, type, review status, privacy level, version, linked record IDs, extraction state, and the provider file identifier needed for future controlled access. It does not store presigned URLs, raw tokens, or private document text just because those values were available during upload.
Link evidence where work actually happens
Evidence has to meet the operator inside the primary workflow. If normal work happens in a direct form, document upload belongs there. If the user needs help filling fields, chat can sit beside the form as an assistant, but the reviewed product form should remain the save boundary.
That distinction matters. Chat can reduce friction, but the official record should still be created by typed product code. When files are attached during intake, the product can create document records first, attach their generated document IDs to the new business record, and then show evidence status after save. The operator should see whether required evidence is present, missing, or linked but still awaiting review.
Keep the inbox for recovery and linking
Sequential workflows fail. A file upload may succeed before a later record save fails. A document may arrive before the operator knows the right transaction or entity to link it to. A chat-assisted draft may collect useful evidence before the final review decision exists.
That is why a document inbox is not a nice-to-have. It is the recovery surface for the evidence spine. It can highlight unlinked evidence, preserve the provider fragment or record handle needed for safe updates, and make linking idempotent: add the link once, bump the document version once, and avoid creating duplicate document records for the same evidence.
Detail pages should resolve meaning, not expose handles
A document detail page is useful only if it turns relationships into meaning. Showing raw linked record IDs is a start, but it is not enough for an operator trying to answer “what is this evidence supporting?” The detail view should resolve known links into readable summaries: record type, date, status, amount or count where appropriate, and a protected path back to the relevant working surface.
The same page should preserve unresolved IDs explicitly instead of hiding them. Unknown links are operational facts. They may point to records from an older version, imported data, or a future type the current UI does not yet resolve. Keeping them visible prevents silent evidence loss while still avoiding raw file URLs and temporary access links.
Handoff should use sanitized packages
Once evidence becomes part of the product's spine, outside review does not need broad workspace access by default. A narrow handoff can render a specific saved report snapshot, its evidence checklist, open questions, and checksum into a sanitized package. If a share link is needed, it should be scoped to that exact package and expire.
That keeps the source of truth inside the private product. The reviewer receives what they need to inspect, not the power to browse unrelated workspace state or raw file handles. The owner can regenerate or revoke future handoffs according to the product's actual trust model.
The rule I am taking forward
For private workflows, evidence is not just storage. It is how the product proves its own state, recovers from partial failures, and gives humans confidence that a decision or report is supported.
Store private files carefully. Store evidence relationships deliberately.
The next time I build a document-heavy workflow, I will start from the evidence spine: durable document records, safe metadata, idempotent linking, protected detail views, visible missing-evidence state, and handoff artifacts that prove exactly what they contain without leaking the private substrate beneath them.