# Data model

Core ledger types and relationships.

BennyBooks has three primitives: transactions, notes, and receipts. Categories use stable codes from the ontology — see Reference → Ontology.

## Transaction

| Field | Type | Notes |
| --- | --- | --- |
| id | uuid | Primary key |
| date | date | YYYY-MM-DD |
| amount | number | Negative = outflow, positive = inflow |
| currency | string | Default EUR |
| description | string | Vendor / memo |
| category | string? | Canonical chart name; null = uncategorized |
| status | enum | See Transactions API page |
| source | enum | nordea | stripe | manual_csv |
| externalId | string? | Connector dedup key |
| suggestedBy | string? | Set when agent proposes category |
| confidence | number? | 0.0–1.0 |
| reason | string? | Human-readable explanation |

## Note

| Field | Type | Notes |
| --- | --- | --- |
| id | uuid | Primary key |
| transactionId | uuid | Parent transaction |
| content | string | Free text |
| authorUserId | string? | User or mcp:token id |

## Receipt

| Field | Type | Notes |
| --- | --- | --- |
| id | uuid | Primary key |
| transactionId | uuid? | null if unlinked |
| fileName | string | Original filename |
| mimeType | string | MIME type |
| sizeBytes | integer | File size |
| ocrText | string? | Extracted text when available |

## Proposal

| Field | Type | Notes |
| --- | --- | --- |
| id | uuid | Primary key |
| type | enum | categorization | note | receipt_link |
| status | enum | pending | approved | rejected |
| payload | object | Includes category, categoryCode, evidence when applicable |
| proposedBy | string | mcp:token_id |
| confidence | number? | Agent confidence |
| reason | string? | Explanation |

## Audit log

Human UI: /log. Agents have no read endpoint in v1. See Guides → Audit Log.

| Field | Type | Notes |
| --- | --- | --- |
| id | uuid | Primary key |
| actor | string | mcp:<tokenId> or user:<clerkUserId> |
| tool | string | e.g. propose_categorization, approve_proposal |
| payload | object | Request / review context |
| proposalId | uuid? | Links propose → approve/reject |
| createdAt | timestamptz | When the action was recorded |