# Concept Model

## Core Entities and Relationships

```mermaid
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