---
title: Data model
description: Core ledger types and relationships.
canonical: https://bennybooks.com/developers/reference/data-model
markdown: https://bennybooks.com/developers/reference/data-model.md
---
# Data model

Core ledger types and relationships.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

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 | revolut |
| 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: https://bennybooks.com/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 |

---

## Machine-readable

- HTML: https://bennybooks.com/developers/reference/data-model
- Markdown: https://bennybooks.com/developers/reference/data-model.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Data model",
  "description": "Core ledger types and relationships.",
  "url": "https://bennybooks.com/developers/reference/data-model",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/reference/data-model",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/reference/data-model.md",
    "encodingFormat": "text/markdown",
    "name": "Data model (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
