Organisations Domain

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

Entity Hierarchy

Key Concepts

Provisional vs Canonical Organisations

Organisations exist in two states:

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

AI agents enrich organisations with web-sourced data:

Enrichment Flow

The orchestrator application/jobs/organisation/enrich.ts chains the four agents (search → enrich → match → verify) behind the organisation.enrich Inngest event.

Identity vs intel (when enrichment re-runs)

Enrichment has two lifecycles:

match / verify live inside enrich.ts, so gating that job on profile status is what keeps identity to a single run. See ADR-0006 for the full action → ensure-enriched → pure-snapshot report model.

Transaction Types

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

Related Files