MyMidas/TAX_FEATURE_PLAN.md

# Tax Feature — Implementation Plan

## Goal

Add a UK tax reporting section to MyMidas that lets a PAYE employee enter their tax code and payslip/P60 data, then automatically calculates their income tax, NI, capital gains, and dividend tax liabilities for a selected tax year — showing what's been withheld, what's owed, and a full breakdown report.

---

## Scope (Phase 1)

- UK only, Rest of England / Wales / Northern Ireland tax bands (not Scotland)
- PAYE employment — single employer per tax year (schema supports more)
- Income data via monthly payslips or annual P60
- Capital gains auto-calculated from existing investment disposals + manual entry option
- Dividend tax auto-calculated from existing investment dividend transactions
- No student loan, no self-employment income, no pension contributions modelling
- Tax lives as a **dedicated sidebar page** (`/tax`) — not a tab inside Reports

Out of scope for Phase 1, possible Phase 2:
- Scotland rates
- Multiple employments
- Self-assessment / self-employment income
- Pension contribution relief
- Additional countries

---

## Database Schema

### Table: `tax_rate_configs`

Stores the tax rates for each year. Pre-populated by migration; editable in-app via the Tax settings panel so future Budget changes don't require a code deployment or container rebuild.

| Column | Type | Notes |
|---|---|---|
| `id` | UUID PK | |
| `user_id` | UUID FK → users | RLS keyed — each user owns their own copy |
| `tax_year` | INTEGER | e.g. `2025` = year ending 5 April 2025 |
| `rate_type` | VARCHAR(30) | `income_tax` / `ni` / `cgt` / `dividend` |
| `config` | JSONB | Rate bands / thresholds for that type (see format below) |
| `updated_at` | TIMESTAMPTZ | |

Unique constraint: `(user_id, tax_year, rate_type)`.

Migration pre-populates rows for **2025** and **2026** for every new user (see seed data below). The service loads rates from this table (with a short in-process TTL cache) rather than from hardcoded Python constants.

#### Config JSONB format per rate_type

**income_tax** and **ni**:
```json
{
  "bands": [
    {"from": 0,      "to": 12570,  "rate": 0.00},
    {"from": 12571,  "to": 50270,  "rate": 0.20},
    {"from": 50271,  "to": 125140, "rate": 0.40},
    {"from": 125141, "to": null,   "rate": 0.45}
  ]
}
```

**cgt**:
```json
{
  "exempt": 3000,
  "basic_rate": 0.18,
  "higher_rate": 0.24
}
```

**dividend**:
```json
{
  "allowance": 500,
  "basic_rate": 0.0875,
  "higher_rate": 0.3375,
  "additional_rate": 0.3935
}
```

#### Seed data (2025 and 2026)

2025 = year ending 5 April 2025 (2024/25). CGT rates reflect the October 2024 Budget change (18%/24% effective 30 Oct 2024 — applied to the full year for simplicity; note in disclaimer).

2026 = year ending 5 April 2026 (2025/26). Income tax thresholds remain frozen; NI, CGT, and dividend rates unchanged from 2025.

```python
SEED_RATE_CONFIGS = {
    2025: {
        "income_tax": {"bands": [
            {"from": 0,      "to": 12570,  "rate": 0.00},
            {"from": 12571,  "to": 50270,  "rate": 0.20},
            {"from": 50271,  "to": 125140, "rate": 0.40},
            {"from": 125141, "to": None,   "rate": 0.45},
        ]},
        "ni": {"bands": [
            {"from": 0,      "to": 12570,  "rate": 0.00},
            {"from": 12571,  "to": 50270,  "rate": 0.08},
            {"from": 50271,  "to": None,   "rate": 0.02},
        ]},
        "cgt": {"exempt": 3000, "basic_rate": 0.18, "higher_rate": 0.24},
        "dividend": {"allowance": 500, "basic_rate": 0.0875,
                     "higher_rate": 0.3375, "additional_rate": 0.3935},
    },
    2026: {
        "income_tax": {"bands": [
            {"from": 0,      "to": 12570,  "rate": 0.00},
            {"from": 12571,  "to": 50270,  "rate": 0.20},
            {"from": 50271,  "to": 125140, "rate": 0.40},
            {"from": 125141, "to": None,   "rate": 0.45},
        ]},
        "ni": {"bands": [
            {"from": 0,      "to": 12570,  "rate": 0.00},
            {"from": 12571,  "to": 50270,  "rate": 0.08},
            {"from": 50271,  "to": None,   "rate": 0.02},
        ]},
        "cgt": {"exempt": 3000, "basic_rate": 0.18, "higher_rate": 0.24},
        "dividend": {"allowance": 500, "basic_rate": 0.0875,
                     "higher_rate": 0.3375, "additional_rate": 0.3935},
    },
}
```

When a new user registers, the `tax_rate_configs` rows for 2025 and 2026 are inserted automatically (same place other user-default data is seeded). Adding a future year (e.g. 2027) requires inserting new rows — a small migration — but never a code change.

### Table: `tax_profiles`

One row per tax year. Designed to support multiple employments in future.

| Column | Type | Notes |
|---|---|---|
| `id` | UUID PK | |
| `user_id` | UUID FK → users | RLS keyed |
| `tax_year` | INTEGER | e.g. `2025` = year ending 5 April 2025 |
| `employer_name_enc` | BYTEA | AES-256-GCM encrypted |
| `tax_code` | VARCHAR(20) | e.g. `1257L`, `BR`, `D0`, `K100` |
| `is_cumulative` | BOOLEAN | `true` = cumulative basis, `false` = W1/M1 |
| `created_at` | TIMESTAMPTZ | |
| `updated_at` | TIMESTAMPTZ | |

Unique constraint: `(user_id, tax_year)`.

### Table: `payslips`

Monthly payslip entries, or a single P60 annual entry.

| Column | Type | Notes |
|---|---|---|
| `id` | UUID PK | |
| `user_id` | UUID FK → users | RLS keyed |
| `tax_profile_id` | UUID FK → tax_profiles | |
| `period_month` | SMALLINT | 1–12; `NULL` if `is_p60 = true` |
| `period_year` | SMALLINT | Calendar year of the payslip |
| `gross_pay` | NUMERIC(14,2) | |
| `income_tax_withheld` | NUMERIC(14,2) | |
| `ni_withheld` | NUMERIC(14,2) | |
| `net_pay` | NUMERIC(14,2) | |
| `is_p60` | BOOLEAN | `true` = this is the annual P60 figure |
| `notes_enc` | BYTEA | AES-256-GCM encrypted, optional |
| `created_at` | TIMESTAMPTZ | |

When a P60 is entered for a tax year, all existing individual payslips for that profile are deleted and replaced by the single P60 row (confirmed via a warning dialog in the UI).

### Table: `manual_cgt_disposals`

For assets not tracked in the investments section (e.g. property, share schemes, other).

| Column | Type | Notes |
|---|---|---|
| `id` | UUID PK | |
| `user_id` | UUID FK → users | RLS keyed |
| `tax_year` | INTEGER | |
| `disposal_date` | DATE | |
| `asset_description_enc` | BYTEA | AES-256-GCM encrypted |
| `proceeds` | NUMERIC(14,2) | |
| `cost_basis` | NUMERIC(14,2) | |
| `notes_enc` | BYTEA | AES-256-GCM encrypted |
| `created_at` | TIMESTAMPTZ | |

`gain_loss` is **not stored** — computed in the service as `proceeds − cost_basis`.

---

## Tax Calculation Engine

### File: `backend/app/services/tax_service.py`

Rates are loaded from `tax_rate_configs` (DB), not hardcoded. The service caches the loaded config per `(user_id, tax_year)` for the lifetime of the request.

#### Tax year helper

UK tax year runs 6 April → 5 April. Convention: `tax_year=2025` means the year **ending** 5 April 2025 (the 2024/25 tax year).

```python
def tax_year_for_date(d: date) -> int:
    """Return the tax_year int for a given date. tax_year=N means 6 Apr (N-1) → 5 Apr N."""
    if (d.month, d.day) >= (4, 6):
        return d.year + 1
    return d.year
```

#### Core functions

All calculation functions receive a `rates: dict` argument (the loaded config for that year/type) rather than reading from constants.

```python
async def load_rates(db, user_id, tax_year) -> dict:
    # Returns {"income_tax": {...}, "ni": {...}, "cgt": {...}, "dividend": {...}}
    # Loads from tax_rate_configs table; raises 404 if year not configured

def parse_tax_code(code: str) -> dict:
    # Returns: {"allowance": int, "rate_override": float | None, "k_code": bool}

def calculate_income_tax(gross_income: Decimal, tax_code: str, rates: dict) -> dict:
    # Returns: {"personal_allowance": Decimal, "taxable_income": Decimal,
    #           "liability": Decimal, "band_breakdown": [...]}

def calculate_ni(gross_income: Decimal, rates: dict) -> dict:
    # Returns: {"liability": Decimal, "band_breakdown": [...]}

def calculate_cgt(gains: Decimal, gross_income: Decimal, rates: dict) -> dict:
    # Determines basic vs higher rate from remaining basic rate band
    # Returns: {"gross_gain": Decimal, "exempt": Decimal, "taxable_gain": Decimal,
    #           "rate_applied": float, "liability": Decimal}

def calculate_dividend_tax(dividends: Decimal, gross_income: Decimal, rates: dict) -> dict:
    # Returns: {"gross_dividends": Decimal, "allowance": Decimal,
    #           "taxable_dividends": Decimal, "liability": Decimal, "rate_applied": float}

async def build_tax_report(db, user_id, tax_year) -> dict:
    # Loads rates, pulls payslip totals, investment disposals, dividend transactions
    # Returns the full report payload
```

#### Tax code parser

| Code pattern | Behaviour |
|---|---|
| `1257L`, `1257M`, `1257N` | allowance = digits × 10 |
| `BR` | allowance = 0, flat 20% on all income |
| `D0` | flat 40% on all income |
| `D1` | flat 45% on all income |
| `NT` | no tax |
| `K100` | negative allowance: taxable income += digits × 10 |
| `0T` | allowance = 0, standard bands apply |
| `W1`/`M1` suffix | non-cumulative (informational only for Phase 1) |

Personal allowance taper: reduce by £1 for every £2 of income above £100,000, down to zero at £125,140.

---

## Backend API

### File: `backend/app/api/v1/tax.py`

All routes prefixed `/tax`.

| Method | Path | Description |
|---|---|---|
| GET | `/tax/rate-configs` | List configured tax years for this user |
| GET | `/tax/rate-configs/{tax_year}` | Get full rate config for a year |
| PUT | `/tax/rate-configs/{tax_year}` | Create or update rate config for a year |
| GET | `/tax/profile/{tax_year}` | Get profile for a tax year (404 if none) |
| PUT | `/tax/profile/{tax_year}` | Create or update profile (tax code, employer name) |
| GET | `/tax/payslips/{tax_year}` | List payslips for a tax year |
| POST | `/tax/payslips/{tax_year}` | Add a payslip |
| PUT | `/tax/payslips/{id}` | Edit a payslip |
| DELETE | `/tax/payslips/{id}` | Delete a payslip |
| POST | `/tax/payslips/{tax_year}/p60` | Enter P60 — replaces all individual payslips |
| GET | `/tax/cgt-disposals/{tax_year}` | List manual CGT disposals |
| POST | `/tax/cgt-disposals/{tax_year}` | Add a manual disposal |
| PUT | `/tax/cgt-disposals/{id}` | Edit |
| DELETE | `/tax/cgt-disposals/{id}` | Delete |
| GET | `/tax/report/{tax_year}` | Full computed tax report for a year |

### Pydantic schemas: `backend/app/schemas/tax.py`

- `TaxRateConfigUpdate` / `TaxRateConfigResponse`
- `TaxProfileCreate` / `TaxProfileResponse`
- `PayslipCreate` / `PayslipResponse`
- `P60Entry` (gross_pay, income_tax_withheld, ni_withheld, net_pay)
- `ManualDisposalCreate` / `ManualDisposalResponse`
- `TaxReportResponse`

---

## Migration

New Alembic migration: `add_tax_tables`

- Creates `tax_rate_configs`, `tax_profiles`, `payslips`, `manual_cgt_disposals`
- Adds RLS policies (same pattern as other tables: `app.current_user_id`)
- Encrypted columns stored as `_enc bytea`: `employer_name_enc`, `notes_enc`, `asset_description_enc`
- Seeds `tax_rate_configs` rows for 2025 and 2026 for all existing users inside the migration (so existing accounts get rates without re-registering)

---

## Frontend

### Nav changes

Add `{ href: "/tax", icon: Receipt, label: "Tax" }` to both:
- `frontend/src/components/layout/Sidebar.tsx` — between Reports and Predictions
- `frontend/src/components/layout/MobileNav.tsx` — same position
- `frontend/src/App.tsx` — add `/tax` route pointing to `TaxPage`

### API client: `frontend/src/api/tax.ts`

Typed functions for all endpoints. Interfaces for:
- `TaxRateConfig`, `TaxRateConfigUpdate`
- `TaxProfile`, `TaxProfileCreate`
- `Payslip`, `PayslipCreate`, `P60Entry`
- `ManualDisposal`, `ManualDisposalCreate`
- `TaxReport`

### Page: `frontend/src/pages/tax/TaxPage.tsx`

Top-level page at `/tax`. Contains the full tax UI.

#### Layout

```
[ Tax Year selector: 2024/25 | 2025/26 | ... ]          [ Rate Config button (edit rates for year) ]

[ Tax Profile card ]
  Employer: Acme Ltd    Tax Code: 1257L    [ Edit ]

[ Income & PAYE section ]
  Payslip table (month | gross | tax withheld | NI withheld | net)
  [ + Add Payslip ]  [ Enter P60 ]
  Summary row: totals

[ Tax & NI Summary card ]
  Gross income        £xx,xxx
  Personal allowance  £12,570
  Taxable income      £xx,xxx
  ─────────────────────────────────────────
  Income tax liability   £x,xxx    Withheld   £x,xxx    [ Owed / Overpaid ]
  NI liability           £x,xxx    Withheld   £x,xxx    [ Owed / Overpaid ]

[ Capital Gains section ]
  Auto-detected disposals from investments (read-only table)
  Manual disposals table  [ + Add Disposal ]
  Summary: total gains | exempt | taxable | estimated CGT

[ Dividends section ]
  Auto-detected from investment dividend transactions (read-only)
  Summary: total dividends | allowance | taxable | estimated dividend tax

[ Overall Liability card ]
  ┌──────────────────────────────────────────┐
  │ Total liability       £x,xxx             │
  │ Total withheld        £x,xxx             │
  │ ───────────────────────────────────────  │
  │ Net owed to HMRC / Overpaid   £x,xxx    │
  └──────────────────────────────────────────┘

[ Disclaimer: estimates only — not financial advice ]
```

#### Components to build (all in `frontend/src/pages/tax/`)

- `TaxPage.tsx` — top-level, holds selected tax year state
- `TaxYearSelector.tsx` — dropdown of configured years
- `RateConfigModal.tsx` — shows/edits the JSONB rate bands for the selected year (table of bands, editable inputs)
- `TaxProfileCard.tsx` — shows/edits tax code and employer name
- `PayslipTable.tsx` — list, add, edit, delete; "Enter P60" button with confirmation dialog
- `PayslipFormModal.tsx` — single payslip month form
- `P60Modal.tsx` — four-field form (gross, tax withheld, NI withheld, net) with warning dialog
- `TaxNISummaryCard.tsx` — computed liability vs withheld, owed/overpaid highlighted
- `CGTSection.tsx` — auto + manual disposal tables, summary
- `ManualDisposalFormModal.tsx`
- `DividendSection.tsx` — auto-pulled, summary only
- `OverallLiabilityCard.tsx` — final totals

---

## Implementation Order

1. **Migration** — create the four tables with RLS policies; seed 2025/2026 rate configs for existing users
2. **Tax calculation engine** (`tax_service.py`) — pure functions taking `rates: dict`, unit-testable without DB
3. **Backend models** (`db/models/tax.py`) — SQLAlchemy mapped classes
4. **Pydantic schemas** (`schemas/tax.py`)
5. **Service layer** — DB queries for CRUD + `load_rates()` + `build_tax_report()`
6. **API endpoints** (`api/v1/tax.py`) + register in `router.py`
7. **Frontend API client** (`api/tax.ts`)
8. **Nav wiring** — add Tax to Sidebar, MobileNav, App.tsx routes
9. **Tax page UI** — build components top-to-bottom following the layout above
10. **Rate config UI** — `RateConfigModal` so rates can be edited without touching code
11. **End-to-end test** — enter a full year of payslips, verify liability matches HMRC calculator

---

## Testing Checkpoints

- Tax code parser: `1257L`, `BR`, `D0`, `K100`, `0T`, `1257M`
- Income tax: verify bands at £12,570 / £50,270 / £100,000 (taper) / £125,140
- NI: verify thresholds
- CGT: basic rate (18%) vs higher rate (24%) taxpayer
- P60 replacement: individual payslips deleted before P60 insert
- Investment disposal auto-detection: verify `tax_year_for_date` boundary (6 Apr)
- Rate config: edit a band value, confirm report recalculates using new value

---

## Notes & Decisions

- **Tax year convention**: `tax_year = 2025` = year ending 5 April 2025 = 2024/25. Always display as "2024/25" in the UI.
- **Configurable rates (Option A)**: Rates live in `tax_rate_configs` DB table. Pre-populated for 2025 and 2026. When a new Budget changes rates, the user edits them in-app via `RateConfigModal` — no code change or rebuild needed. Adding a brand new tax year requires a small migration to insert new rows, but that's still no code change in the calculation logic.
- **Encrypted fields**: `employer_name_enc`, `notes_enc`, `asset_description_enc` — all PII stored as `_enc bytea` using `encrypt_field`/`decrypt_field` from `core/security.py`.
- **`gain_loss` not stored**: Computed in service as `proceeds − cost_basis`. Not a DB column.
- **CGT rates (post Oct 2024 Budget)**: 18% basic rate, 24% higher rate. For 2024/25 (tax_year=2025), the change was effective 30 Oct 2024 mid-year — the seeded rate uses 18%/24% for the full year with a disclaimer note in the UI.
- **CGT rate determination**: Requires knowing whether the user is basic or higher rate (remaining basic rate band after income). `build_tax_report()` computes income tax first, then passes the remaining band to `calculate_cgt()`.
- **Sidebar placement**: Tax sits between Reports and Predictions in both `Sidebar.tsx` and `MobileNav.tsx`.
- **Disclaimer**: Report UI must include a visible note that figures are estimates for informational purposes only and are not financial or tax advice.
- **Future expansion**: `tax_profiles` unique constraint is `(user_id, tax_year)` for now — relax to allow multiple rows per year when multi-employment is added.