ai-tax-agent/docs/ONTOLOGY.md

Concept Model

Core Entities and Relationships

graph TB
    TP[TaxpayerProfile] --> TY[TaxYear]
    TY --> J[Jurisdiction]
    TF[TaxForm] --> TY
    TF --> S[Schedule]
    S --> FB[FormBox]

    D[Document] --> E[Evidence]
    E --> II[IncomeItem]
    E --> EI[ExpenseItem]
    E --> P[Payment]

    TP --> II
    TP --> EI
    TP --> PA[PropertyAsset]
    TP --> BA[BusinessActivity]
    TP --> PC[PensionContribution]
    TP --> SLP[StudentLoanPlan]

    Party --> II
    Party --> EI
    Party --> Account

    II --> S
    EI --> S
    PA --> S

    C[Calculation] --> FB
    R[Rule] --> C

    ER[ExchangeRate] --> II
    ER --> EI

    NE[NormalizationEvent] --> II
    NE --> EI

    ETL[ETLRun] --> D
    ETL --> E

    CB[Consent] --> TP

Entity Descriptions

Core Tax Entities

• TaxpayerProfile: Individual, partnership, or company with tax obligations
• TaxYear: Fiscal period (UK: 6 April - 5 April) with jurisdiction-specific rules
• Jurisdiction: Tax authority region (UK, with potential for other jurisdictions)
• TaxForm: Official forms (SA100, SA102, SA103, SA105, SA110, SA108)
• Schedule: Sections within forms (Employment, Self-Employment, Property, etc.)
• FormBox: Individual fields/boxes on forms with specific calculation rules

Document & Evidence

• Document: Source materials (bank statements, invoices, receipts, P&L, etc.)
• Evidence: Specific snippets from documents with provenance (page, bbox, text hash)

Financial Entities

• IncomeItem: Employment, self-employment, property, dividend, interest income
• ExpenseItem: Business expenses, property costs, allowable deductions
• Payment: Transactions to/from HMRC, employers, clients
• PropertyAsset: Real estate holdings with usage classification
• BusinessActivity: Trading activities with SIC codes and basis periods

Parties & Accounts

• Party: Employers, payers, banks, landlords, tenants with identification numbers
• Account: Bank accounts with IBAN, sort codes, account numbers

Calculation & Rules

• Calculation: Formula applications with versioned inputs/outputs
• Rule: Tax regulations with effective periods and references
• Allowance/Relief: Tax allowances with caps, rates, eligibility
• ExchangeRate: Currency conversions with date and source

Compliance & Operations

• Consent/LegalBasis: GDPR compliance with purpose and scope
• ETLRun: Data processing jobs with success/error tracking
• NormalizationEvent: Data cleaning and standardization records

Cardinalities

Relationship	From	To	Cardinality
BELONGS_TO	Schedule	TaxForm	N:1
OF_TAX_YEAR	TaxForm	TaxYear	N:1
IN_JURISDICTION	TaxYear	Jurisdiction	N:1
HAS_BOX	Schedule	FormBox	1:N
DERIVED_FROM	IncomeItem/ExpenseItem	Evidence	N:N
SUPPORTED_BY	Evidence	Document	N:1
PAID_BY	Payment	Party	N:1
OWNS	TaxpayerProfile	PropertyAsset	N:N
EMPLOYED_BY	TaxpayerProfile	Party	N:N
APPLIES_TO	ExchangeRate	IncomeItem/ExpenseItem	1:N
COMPUTES	Calculation	FormBox	N:1
HAS_VALID_BASIS	TaxpayerProfile	Consent	1:N
CITES	Calculation/Rule	RAGChunk	N:N
DESCRIBES	RAGChunk	IncomeItem/ExpenseItem	N:N

Temporal Model

All financial facts implement bitemporal modeling:

• valid_time: When the fact was true in reality (valid_from, valid_to)
• system_time: When the fact was recorded in the system (asserted_at, retracted_at)

This enables:

• Time-travel queries to any point in time
• Audit trails of all changes
• Correction of historical data without losing provenance
• Multi-year tax calculations with proper period alignment