Partners & Suppliers

The SCM application has a multi-model approach to represent external business relationships:

graph TD
    User --> Party
    User --> Partner
    User --> Partnership
    User --> OrgRelation

1. Party Model (Transaction Entities)

Purpose: Low-level transactional entity for Purchase Orders, Invoices, Shipments.

1model Party {
2  id              String
3  organizationId  String
4  partyTypeId     String    "cmt">// Links to PartyType (Supplier, Customer, etc.)
5  class           String    "cmt">// ORGANIZATION or PERSON
6  name            String
7  roles           PartyRole[]    "cmt">// Used in transactions
8  supplierPurchaseOrders  PurchaseOrder[]  @relation("POSupplier")
9  invoicesFrom            Invoice[]
10  invoicesTo              Invoice[]
11}

Key Usage

• PurchaseOrder.supplierPartyId → references a Party
• ProductSupplier.supplierId → links products to their suppliers
• Invoice.partyId → billing party

Party Roles

| Role | Description | | :--- | :--- | | SUPPLIER | Vendor you buy from | | CUSTOMER | Organization you sell to | | MANUFACTURER | Product manufacturer | | DISTRIBUTOR | Distribution partner | | THIRD_PARTY_LOGISTICS | 3PL provider |

2. Partner Model (Operational Management)

Purpose: SCM-native partner management with addresses, contacts, locations.

1model Partner {
2  id              String
3  organizationId  String    "cmt">// Your org owns this partner record
4  name            String
5  type            PartnerType   "cmt">// SUPPLIER, CUSTOMER, CARRIER, etc.
6  status          PartnerStatus "cmt">// ACTIVE, INACTIVE, SUSPENDED
7  
8  "cmt">// Operational settings
9  taxId           String?
10  paymentTerms    String?
11  incoterm        String?
12  centralPurchasing Boolean
13  poPrefix        String?       "cmt">// For PO numbering
14  
15  "cmt">// Related data
16  addresses       PartnerAddress[]
17  contacts        PartnerContact[]
18  locations       PartnerLocation[]   "cmt">// Links to shared locations
19}

Partner Types

• SUPPLIER: Vendors you purchase from
• CUSTOMER: Organizations you sell to
• CARRIER: Shipping/logistics providers
• MANUFACTURER: Product manufacturers
• DISTRIBUTOR: Distribution partners
• INTERNAL: Internal divisions
• OTHER: Misc partners

Key Features

• Addresses: Billing, shipping, returns addresses per partner
• Contacts: Named contacts with roles (Sales, Support, Accounting)
• Locations: Link partners to shared Location records (warehouses, stores)
• Central Purchasing: Allow parent to purchase on behalf of children

3. Partnership Model (Cross-Organization)

Purpose: Formal B2B relationships between separate Organizations.

1model Partnership {
2  id                    String
3  organizationId        String    "cmt">// Requesting org
4  partnerOrganizationId String    "cmt">// Partner org
5  status                PartnershipStatus  "cmt">// REQUESTED, ACCEPTED, DENIED
6  partyRole             PartyRoleType      "cmt">// Role they play for you
7  relationshipType      RelationshipType   "cmt">// BUYER_SELLER, LOGISTICS, etc.
8  
9  "cmt">// Invitation workflow
10  invitationToken       String?
11  invitationEmail       String?
12  invitationSentAt      DateTime?
13  invitationAcceptedAt  DateTime?
14}

Partnership Workflow

sequenceDiagram
    participant Org A as Org A (Requester)
    participant Invite as Invitation
    participant Org B as Org B (Partner)
    
    Org A->>Invite: Request
    Note right of Invite: PENDING
    Invite->>Org B: Accept
    Note right of Org B: Active Partnership

Relationship Types

• BUYER_SELLER: Standard procurement relationship
• LOGISTICS: 3PL/shipping partnership
• MANUFACTURING: Contract manufacturing
• DISTRIBUTION: Distribution agreement
• FRANCHISE: Franchise relationship

4. OrganizationRelation (Org Hierarchy)

Purpose: Define structural relationships between organizations (including PARTNER role).

1model OrganizationRelation {
2  parentOrgId  String
3  childOrgId   String
4  role         String    "cmt">// SUBSIDIARY, DIVISION, PARTNER, AFFILIATE
5  isActive     Boolean
6}

Relation Roles

| Role | Description | Billing Included | | :--- | :--- | :--- | | SUBSIDIARY | Owned subsidiary | ✅ Yes | | DIVISION | Business division | ✅ Yes | | BRANCH | Branch office | ✅ Yes | | PARTNER | External partner | ❌ No | | AFFILIATE | Affiliate org | ❌ No | | FRANCHISE | Franchise | ❌ No |

How They Work Together

Scenario: Creating a Purchase Order

1. User selects Supplier → Party record (type: SUPPLIER)
2. System loads → Partner record (for payment terms, addresses)
3. PO is created → supplierPartyId = Party.id
4. Supplier org may have → Partnership (if cross-org visibility needed)

API Flow (/api/partners)

The partners API aggregates from 3 sources:

1"cmt">// 1. Partner model (owned by your org)
2const partnersFromModel = await database.partner.findMany({
3  where: { organizationId, type: 'SUPPLIER' }
4});
5 
6"cmt">// 2. OrganizationRelation (PARTNER role)
7const partnersFromRelations = await database.organizationRelation.findMany({
8  where: { parentOrgId: organizationId, role: 'PARTNER' }
9});
10 
11"cmt">// 3. Partnership model (accepted partnerships)
12const partnersFromPartnerships = await database.partnership.findMany({
13  where: { organizationId, status: 'ACCEPTED' }
14});

Key Flags on Organization

1model Organization {
2  isCustomer       Boolean   "cmt">// Can be sold to
3  isSupplier       Boolean   "cmt">// Can be purchased from
4  partnershipTier  PartnershipTier?  "cmt">// PARTNER_ONLY, BASIC, FULL
5}

These flags determine:

• isSupplier=true → Appears in supplier dropdowns for POs
• isCustomer=true → Appears in customer dropdowns for Sales Orders
• partnershipTier → Controls what partnership features are available

Summary Table

| Model | Purpose | Scope | Used For | | :--- | :--- | :--- | :--- | | Party | Transaction entity | Per-org | POs, Invoices, Shipments | | Partner | Operational config | Per-org | Addresses, contacts, terms | | Partnership | Cross-org link | Multi-org | Visibility, collaboration | | OrganizationRelation | Org hierarchy | Multi-org | Subsidiaries, partners, billing |