Molino⺢ Practice

H1Document PRD - Molino App

version: 2026.04 status: locked owner: Molino scope: app/documents last_updated: 2026-04-26

H2Focus Strip

Now	Lock	Do Not Break	Next Closure
Project commercial data without owning it	Document as projection only	Offer/Order/LineItem totals, Folio page engine	Use canonical Offer -> Order read/action once locked

State	Meaning
built/locked	`ProjectDocument`, `DocumentPage`, Folio page actions
built/partial	`documentToOrder()`, trip pricing action, line-item display block
docs-ahead	document-to-offer commercial commit and no local total recompute

H10. Implementation Snapshot

H2Current goal

H3Keep Document as the in-app projection instrument

Use it for structured content, commercial artifacts, and trip handoff.

H2Remaining features

H3Preserve deterministic document rendering and PDF export

Keep the render path stable.

H3Keep document section data serializable and auditable

Make each section easy to inspect and transport.

H3Make trip generation handoff explicit without moving Trip, Offer, or Order truth into documents

Preserve the document-as-projection boundary.

H3Keep projection writes inside actions or projection helpers

Do not move projection authority into UI components.

H2Next build steps

H3Inspect `app/documents/page.tsx`, `app/documents/api/route.ts`, and document sanitizers before changing flow

Check the current document boundary before editing.

H3Verify document render payloads derive from canonical data

Keep the render payloads rooted in source truth.

H3Keep `LineItem`, `Offer`, and `Order` totals outside document recomputation

Do not duplicate commercial totals in the document layer.

H3Test document render/export paths after projection changes

Validate the output after any projection update.

H2Prompt starter summary

H3Keep Document as a projection and composition layer

Use read-oriented pages, action-owned mutations, deterministic rendering, and explicit trip-generation handoff.

H2Prompt starter

Implement the next Document PRD slice. Use _PRD/document/README.md as source of truth. Treat Document as a projection and composition layer, not the source of truth for Trip, Offer, Order, or LineItem state. Keep page surfaces read-oriented, mutations and projection writes in actions/helpers, and section payloads serializable and auditable. Preserve deterministic document rendering, PDF export, and explicit trip-generation handoff. Do not move commercial totals or downstream authority into document components.

H21. Product Identity

H3Name

Document

H3One-line Definition

Document is the canonical in-app document instrument for section orchestration, offer projection, and trip generation handoff.

H3User-facing Purpose

This feature exists so users can:

assemble or review structured document content
project offers and exportable artifacts
generate trips from document input when needed
keep commercial sections readable and auditable

H3Internal Platform Purpose

Inside Molino App, this feature exists to:

preserve the document as a working projection surface
keep Trip, Offer, and Order truth outside the document layer
connect canonical data to generated artifacts
support section-based composition without duplicating business logic

H22. Scope

H3In Scope

route: /documents
app folder: app/documents/
api surface: app/documents/api/route.ts, app/api/doc/route.ts
models: Document, ProjectDocument, DocumentPage, LineItem, Offer, Order
projections: document render payloads, PDF export, trip generation handoff
actions: document read/write and projection helpers

H3Out of Scope

using documents as the source of truth for trip or order state
replacing Prisma with client state
turning the document engine into a generic CMS

H23. Authority Model

document page surfaces orchestrate reads
actions own mutation and projection writes
generated artifacts are projections, not canonical truth
section data must remain serializable and auditable

H24. Current Implementation Surface

app/documents/page.tsx
app/documents/api/route.ts
app/lib/renderPdf.ts
app/lib/json.ts
app/lib/sanitize/sanitizeDocument.ts
app/lib/sanitize/sanitizeLineItem.ts
document notes in _PRD/tools/document/ and _PRD/document/archive/

H24.1 Code Audit - 2026-04-26

H3Built / locked

ProjectDocument and DocumentPage are the current Prisma-backed document entities.
Folio document actions read/write document engine data and page surfaces through server actions under app/documents/components/folio/actions/.
Pagination commit actions revalidate /documents/[documentId] after writing document/page state.

H3Built / partial

documentToOrder() can create an order from a document-bound offer and copy offer line items into order-owned line items.
computeTripPricingAction() lets documents or editors call the trip engine without owning pricing authority.
Documents2LineItemsBlock can display line items and totals and can edit items when given an onChange handler.

H3Docs-ahead / pending

app/documents/actions/commitDocumentToOffer.ts currently contains pagination commit logic, not document-to-offer commercial commit logic. Do not rely on that filename as a commercial action until it is renamed or replaced.
Documents2LineItemsBlock recomputes subtotal/tax/total when totals are not passed in. For commercial documents, pass canonical totals from offer/order reads instead of letting the component invent them.
documentToOrder() currently recomputes copied line item totals and tax during order creation; the commercial rule should preserve committed offer line-item totals when creating an order snapshot.

H3Critical next step

After the canonical Offer -> Order action is locked in Commercial, update Document actions and blocks so document projections consume that canonical action/read model and never recompute commercial totals locally.

H25. Acceptance Criteria

document pages render from canonical data
projection output stays deterministic
trip generation handoff remains explicit
old notes stay archived locally instead of being deleted

H26. Locked Summary

Document is Molino's working projection surface for structured content, commercial artifacts, and trip handoff. It must remain a projection layer, not the authoritative source for downstream commerce.