​

Document Connection - Parent-Child Model

​

Overview

​

Key Concepts

​

Parent-Child Hierarchy

• One child can have many parents - A document can be related to multiple parent documents
• One parent can have many children - A parent document can have multiple child documents
• No “cousins” or “partners” - Documents are only connected through direct parent-child relationships
• Clear hierarchy - Usually revolves around a primary document like a sales order

​

Typical Document Hierarchy

Sales Order (Parent)
├── Sales Invoice (Child)
├── Credit Note (Child)
└── Payment (Child)

​

Implementation

​

Database Schema

• parent_document_id - References the parent document
• child_document_id - References the child document
• Unique constraint on (parent_document_id, child_document_id) to prevent duplicates

​

Core Functions

​

connectDocuments()

import { connectDocuments } from "@cona/core";

const result = await connectDocuments({
  parentDocumentId: "sales_order_123",
  childDocumentIds: ["invoice_456", "credit_note_789"],
  organizationId: "org_123",
});

​

batchConnectDocuments()

import { batchConnectDocuments } from "@cona/core";

const result = await batchConnectDocuments({
  organizationId: "org_123",
  documentRelations: [
    { parentDocumentId: "order_1", childDocumentId: "invoice_1" },
    { parentDocumentId: "order_1", childDocumentId: "payment_1" },
    { parentDocumentId: "order_2", childDocumentId: "invoice_2" },
  ],
});

​

Usage in Integrations

​

Shopify Integration

• Sales Order → Parent document
• Sales Invoice → Child of sales order
• Credit Note → Child of both sales order and sales invoice

​

Reconciliation

1. Inherited Parents → If any document already has a parent, all documents inherit that parent
2. Sales Invoice → Becomes parent when available and no existing parents
3. Fallback → First document becomes parent if no invoice or existing parents

• Payment reconciles with Invoice (Invoice has Sales Order parent) → Payment inherits Sales Order as parent
• Payment reconciles with standalone Invoice → Invoice becomes parent of Payment
• Payment reconciles with Credit Note → First document becomes parent

​

Benefits

1. Clear Hierarchy - Easy to understand document relationships
2. Scalable - Avoids complex interconnected networks
3. Flexible - Supports multiple parents per child when needed
4. Organized - Centers around primary business documents
5. Efficient - Simpler queries for finding related documents

​

Querying Related Documents

​

Find Children of a Parent

const children = await prisma.document_relations.findMany({
  where: { parent_document_id: parentId },
  include: { child_document: true },
});

​

Find Parents of a Child

const parents = await prisma.document_relations.findMany({
  where: { child_document_id: childId },
  include: { parent_document: true },
});

​

Find Siblings (same parent)

const siblings = await prisma.document_relations.findMany({
  where: {
    parent_document_id: {
      in: await prisma.document_relations
        .findMany({
          where: { child_document_id: documentId },
          select: { parent_document_id: true },
        })
        .then((results) => results.map((r) => r.parent_document_id)),
    },
    child_document_id: { not: documentId },
  },
  include: { child_document: true },
});