Event Types & Schema

Every action is an immutable event in PostgreSQL.

Schema

CREATE TABLE events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    type TEXT NOT NULL,                      -- e.g., 'ReceiptAttachmentProposed'
    status TEXT NOT NULL DEFAULT 'PROPOSED',  -- PROPOSED, AUTO_APPROVED, APPROVED, REJECTED, EXECUTED, FAILED
    actor TEXT NOT NULL,                      -- 'book-e', 'review-e', 'human:stig-johnny', 'system:auto-approve'
    data JSONB NOT NULL,                      -- event-specific payload
    parent_id UUID REFERENCES events(id),     -- links approval → proposal, execution → approval
    correlation_id UUID NOT NULL,             -- groups all events for one action
    created_at TIMESTAMPTZ DEFAULT NOW()
);

Event Lifecycle

PROPOSED ──┬──> AUTO_APPROVED ──> EXECUTED
           │
           ├──> APPROVED ──> EXECUTED
           │
           └──> REJECTED

Event Types

Receipt Events

Type	Actor	Payload
ReceiptAttachmentProposed	book-e	merchant, amount, date, vatRate, folioEventId, fileUrl, confidence, reasoning
ReceiptAttachmentApproved	system:auto-approve / review-e / human	proposalId, corrections
ReceiptAttachmentRejected	review-e / human	proposalId, reason
ReceiptAttachmentExecuted	system	proposalId, approvalId, folioResponse

Invoice Events

Type	Actor	Payload
InvoiceRegistrationProposed	book-e	supplier, amount, dueDate, vatRate, lineItems, fileUrl
InvoiceRegistrationApproved	review-e / human	proposalId, corrections
InvoiceRegistrationRejected	review-e / human	proposalId, reason
InvoiceRegistrationExecuted	system	proposalId, fikenPurchaseId

Expense Events

Type	Actor	Payload
ExpenseRegistrationProposed	book-e	employee, amount, category, vatRate, fileUrl
ExpenseRegistrationApproved	review-e / human	proposalId, corrections
ExpenseRegistrationExecuted	system	proposalId, fikenJournalEntryId

Query Events (no review)

Type	Actor	Payload
BalanceQueried	book-e	accounts[]
TransactionsQueried	book-e	count, dateRange
MissingReceiptsChecked	system:cron	count, events[]

Pattern Events

Type	Actor	Payload
PatternLearned	system	merchant, accountCode, vatRate, fromEventId

Correlation

All events for one action share a correlation_id:

-- Full history of one receipt attachment
SELECT type, actor, status, created_at
FROM events
WHERE correlation_id = 'abc-123'
ORDER BY created_at;