Organisations Domain
The Organisations domain handles supplier management, transaction processing, and organisation data enrichment.
Entity Hierarchy
Key Concepts
| Entity | Description |
|---|---|
| Organisation | Company/supplier in the supply chain. Can be provisional or canonical. |
| Transaction | Financial transaction with an organisation (spend or revenue). |
| Identifier | External ID like LEI, ABN, or tax ID for matching/verification. |
| Aquila1 | Industry classification used for footprint calculations. |
| Product | Product or service associated with a transaction. |
| Location | Physical address or operating location of an organisation. |
Provisional vs Canonical Organisations
Organisations exist in two states:
| Type | Description | Neo4j Label |
|---|---|---|
| Provisional | User-created, unverified | :Provisional |
| Canonical | Verified organisation, may have enrichment | None (default) |
Promotion Flow
- User can't find existing org, creates provisional
- Admin reviews the provisional org
- Admin either promotes to canonical, merges with existing, or rejects
Organisation Enrichment
External data from Diffbot provides additional organisation details:
| Data Type | Description |
|---|---|
| Description | Company description and overview |
| Website | Official website URL |
| Logo | Company logo |
| Identifiers | LEI, tax IDs, etc. |
| Locations | Headquarters and operating locations |
| Industries | Industry classifications |
Enrichment Flow
Transaction Types
| Type | Description |
|---|---|
| spend | Money paid to supplier |
| revenue | Money received from customer |
Business Rules
- No duplicate canonical organisations allowed
- Transactions belong to exactly one account
- Amounts converted to USD for footprint calculations
- Industry (Aquila1) required for footprint calculation
- Origin country required for footprint calculation
- Transaction types:
spendorrevenue
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
| Type | Description | Example |
|---|---|---|
| LEI | Legal Entity Identifier | 549300EXAMPLE000001 |
| ABN | Australian Business Number | 51 824 753 556 |
| TAX_ID | Generic tax identifier | Various formats |
| DUNS | Dun & Bradstreet number | 12-345-6789 |
Related Files
| Type | Location |
|---|---|
| GraphQL Schema | packages/core/src/infrastructure/neo4j/schemas/organisation.graphql |
| Repository | packages/core/src/infrastructure/repositories/organisation-repository.ts |
| Use Cases | packages/core/src/application/use-cases/organisation/ |
| Diffbot Integration | packages/core/src/infrastructure/diffbot/ |