Cost Allocations

Overview#

Cost allocation distributes shared costs to the business units, departments, projects, or products that benefit from them. Artifi uses a plugin-based architecture where:

• The backend stores data -- allocation runs, lines, validation, and GL posting
• Plugins and agents handle the logic -- reading data, applying allocation formulas, and submitting results
• No hardcoded drivers -- no headcount, revenue, or formula logic is built into the system
• Fully customizable -- clients can modify the starter plugin or build their own
• Full document traceability -- bidirectional linking from source document through allocation to target GL entry

---

What Is Allocation?#

Cost allocation redistributes shared costs to the areas that benefit from them:

---

Allocation Types#

---

How It Works#

Standalone Allocation (No Source Document)#

For periodic cost distributions (e.g., monthly IT overhead split):

1. Plugin reads GL balances using standard query tools
2. Plugin applies allocation logic (fixed percentages, headcount ratios, etc.)
3. Plugin calculates debit/credit splits across target dimensions
4. Preview shown to user for review
5. Allocation run created in draft status
6. Lines submitted -- system validates balance and accounts
7. Approved -- ready for GL posting
8. Executed -- GL journal entry posted

Document-Linked Allocation (From Source Transaction)#

For allocating specific invoices or transactions:

1. Plugin reads source transaction (e.g., an AP invoice for Slack at 120 EUR)
2. Plugin calculates splits across teams
3. Allocation run created with link to source transaction
4. Lines submitted -- system validates source accounts match the original transaction
5. Approved and executed -- GL journal entry posted with full document chain

Document Chain#

When allocating from a source document, the system maintains a complete audit trail:

Source Transaction        Allocation Run         Target Transaction
(e.g., AP Invoice)        (ALLOC-0007)          (GL Journal Entry)

EE-BILL000527     <----   Source link    ---->   EE-CAL000006
Account: 60002            Run details           DR/CR from lines
Amount: 120.00            Lines + dims

From any document in the chain, you can navigate to every related document -- in the admin dashboard or through the AI assistant.

---

Allocation Run Lifecycle#

Draft --> Calculated --> Approved --> Posted
                      --> Rejected
         Voided <-----------------  Posted

---

Allocation Lines#

Each allocation run contains source and target lines:

• Source lines represent the cost being redistributed (typically credits removing cost from the original dimension)
• Target lines represent where the cost is allocated to (typically debits with specific dimensions)
• Total debits must equal total credits across all lines

Line Fields#

---

Validation Rules#

Basic Validations#

1. Balance -- Total debits must equal total credits (tolerance: $0.01)
2. Accounts -- All account numbers must exist and be active
3. Source + Target -- At least one source line and one target line required
4. Minimum lines -- At least 2 lines
5. Positive amounts -- All amounts must be greater than zero

Source Document Validations#

When an allocation is linked to a source transaction:

1. Account match -- Source allocation lines must use accounts that appear in the source transaction's GL lines
2. Allocation limit -- The allocation amount cannot exceed the remaining unallocated balance for each account
3. Partial allocation -- A multi-line source transaction can have separate allocations per account line

Example Validation Messages#

• "Source line accounts do not appear in the source transaction's GL lines. Available accounts: 2000, 60002"
• "Account 60002 is already fully allocated (120.00 of 120.00) by ALLOC-0007. Void existing allocations first."
• "Source amount 80.00 exceeds remaining unallocated balance of 50.00."

---

Usage Examples#

Example 1: Monthly IT Overhead Split#

Split 10,000 in IT overhead across departments at 60/25/15:

Example 2: Allocating an AP Invoice Across Teams#

Allocate a Slack bill (120 EUR, account 60002) across engineering, product, and sales:

The source account (60002) must match the source transaction, and the total (120.00) cannot exceed the unallocated balance.

Example 3: Partial Allocation#

An invoice has two expense lines (60002 for 120 and 61000 for 350). You can allocate just the office expense (60002) now and create a separate allocation for travel (61000) later. Each account tracks its own allocation balance independently.

Example 4: Voiding an Allocation#

If incorrect percentages were used, void the allocation:

• Creates a reversing GL journal entry automatically
• Frees up the source account amounts for re-allocation

---

GL Posting#

When an allocation run is executed:

1. The allocation type is mapped to a transaction type (COST_ALLOCATION, REVENUE_ALLOCATION, or INTERCOMPANY_CHARGE)
2. An open fiscal period is validated for the run date
3. A GL journal entry is posted with all source and target lines
4. The allocation is recorded in history
5. The run status updates to "posted" with a link to the GL transaction

Voiding#

When an allocation is voided:

1. A reversing GL journal entry is created (all debits become credits and vice versa)
2. The allocation history is marked as reversed
3. The run status changes to "voided"
4. Source account amounts are freed up for re-allocation

---

Admin Dashboard#

Allocation Runs List#

View all allocation runs with filters for entity, status, type, and period. Shows run number, date, type, status, amounts, and document links.

Allocation Run Detail#

Detailed view showing:

• Document Chain -- Visual flow from source document through allocation to target GL entry (with links)
• Run details -- Status, dates, amounts, entity
• Allocation lines -- All source and target lines with accounts, amounts, and dimensions
• Execution history -- Timeline of status changes

Transaction Detail Integration#

When viewing a transaction linked to an allocation:

• As source (e.g., viewing the AP invoice) -- Shows "Allocated" badge with link to allocation run and target GL document
• As target (e.g., viewing the allocation GL entry) -- Shows "Created by allocation" badge with link to source document

---

Starter Plugin#

Every organization ships with the arfiti-core-cost-allocation plugin providing:

• Step-by-step allocation workflow with checkpoints
• Commands for running and previewing allocations
• Reference documentation for 6 allocation methods
• Submission format specification

Clients can customize this plugin or build their own for specialized allocation needs -- revenue sharing, intercompany charges, or industry-specific distribution methods.