Fair Supply LogoFair Supply - Docs

Organisations Domain

The Organisations domain handles supplier management, transaction processing, and organisation data enrichment.

Entity Hierarchy

Key Concepts

EntityDescription
OrganisationCompany/supplier in the supply chain. Can be provisional or canonical.
TransactionFinancial transaction with an organisation (spend or revenue).
IdentifierExternal ID like LEI, ABN, or tax ID for matching/verification.
Aquila1Industry classification used for footprint calculations.
ProductProduct or service associated with a transaction.
LocationPhysical address or operating location of an organisation.

Provisional vs Canonical Organisations

Organisations exist in two states:

TypeDescriptionNeo4j Label
ProvisionalUser-created, unverified:Provisional
CanonicalVerified organisation, may have enrichmentNone (default)

Promotion Flow

  1. User can't find existing org, creates provisional
  2. Admin reviews the provisional org
  3. Admin either promotes to canonical, merges with existing, or rejects

Organisation Enrichment

External data from Diffbot provides additional organisation details:

Data TypeDescription
DescriptionCompany description and overview
WebsiteOfficial website URL
LogoCompany logo
IdentifiersLEI, tax IDs, etc.
LocationsHeadquarters and operating locations
IndustriesIndustry classifications

Enrichment Flow

Transaction Types

TypeDescription
spendMoney paid to supplier
revenueMoney received from customer

Business Rules

  1. No duplicate canonical organisations allowed
  2. Transactions belong to exactly one account
  3. Amounts converted to USD for footprint calculations
  4. Industry (Aquila1) required for footprint calculation
  5. Origin country required for footprint calculation
  6. Transaction types: spend or revenue

Common Operations

Creating a Transaction

import { CreateTransaction } from '@repo/core';

const useCase = new CreateTransaction();
const transaction = await useCase.execute({
  organisationId: 'org-123',
  amount: 50000,
  currency: 'AUD',
  type: 'spend',
  date: new Date('2024-01-15'),
  products: ['product-1'],
  country: 'AU',
});

Finding an Organisation

import { OrganisationRepository } from '@repo/core';

// By ID
const org = await OrganisationRepository.findById('org-123');

// By identifier (LEI, ABN, etc.)
const org = await OrganisationRepository.findByIdentifier({
  type: 'LEI',
  value: '549300EXAMPLE000001',
});

// Search by name
const results = await OrganisationRepository.search({
  query: 'Acme Corp',
  limit: 10,
});

Promoting a Provisional Organisation

import { PromoteProvisionalOrganisation } from '@repo/core';

const useCase = new PromoteProvisionalOrganisation();
await useCase.execute({
  provisionalId: 'prov-123',
  aquila1Codes: ['111', '112'], // Industry codes
});

Identifier Types

TypeDescriptionExample
LEILegal Entity Identifier549300EXAMPLE000001
ABNAustralian Business Number51 824 753 556
TAX_IDGeneric tax identifierVarious formats
DUNSDun & Bradstreet number12-345-6789
TypeLocation
GraphQL Schemapackages/core/src/infrastructure/neo4j/schemas/organisation.graphql
Repositorypackages/core/src/infrastructure/repositories/organisation-repository.ts
Use Casespackages/core/src/application/use-cases/organisation/
Diffbot Integrationpackages/core/src/infrastructure/diffbot/