accounted/dev_docs/base_architecture/PART1_IMPLEMENTATION.md

Part 1: Database Foundation & Compliance Core — Implementation Record

What was implemented

8 Supabase migrations, TypeScript type updates, 4 new service files, and modifications to 3 existing files. No UI changes.

---

Migrations

Migration 11: ALTER Existing Tables

supabase/migrations/20240101000011_alter_existing_tables.sql

• chart_of_accounts — added sru_code text for Skatteverket SRU mapping
• journal_entries — added committed_at timestamptz, reversed_by_id uuid FK→self, reverses_id uuid FK→self, correction_of_id uuid FK→self
• journal_entries — expanded source_type CHECK to include storno, correction, import, system
• journal_entry_lines — added tax_code text, cost_center text, project text
• fiscal_periods — added locked_at timestamptz, retention_expires_at date

Migration 12: Tax Code Engine

supabase/migrations/20240101000012_tax_codes.sql

New table tax_codes with columns: id, user_id, code, description, rate, moms_basis_boxes text[], moms_tax_boxes text[], moms_input_boxes text[], flags (is_output_vat, is_reverse_charge, is_eu, is_export, is_oss, is_system).

RLS: select own + system (user_id IS NULL), insert/update/delete own only.

Seeded 12 system tax codes: MP1 (25%), MP2 (12%), MP3 (6%), MPI, MPI12, MPI6, IV (intra-EU), EUS (EU sale), IP (import), EXP (export), OSS, NONE.

New function seed_tax_codes_for_user(p_user_id) copies system codes to user scope.

Migration 13: Document Archive

supabase/migrations/20240101000013_document_archive.sql

New table document_attachments with: storage fields (storage_path, file_name, file_size_bytes, mime_type), integrity (sha256_hash NOT NULL), version chain (version, original_id FK→self, superseded_by_id FK→self, is_current_version), digitization metadata (uploaded_by, upload_source, digitization_date), linkage (journal_entry_id FK ON DELETE RESTRICT, journal_entry_line_id FK ON DELETE RESTRICT).

No DELETE RLS policy — deletion handled by trigger in migration 17.

Migration 14: Audit Log

supabase/migrations/20240101000014_audit_log.sql

New table audit_log: user_id uuid NOT NULL (no FK cascade — survives user deletion), action text with CHECK constraint, table_name, record_id, actor_id, old_state jsonb, new_state jsonb, description. No updated_at — append-only.

BEFORE UPDATE and BEFORE DELETE triggers raise exception to enforce immutability.

Migration 15: Dimensions

supabase/migrations/20240101000015_dimensions.sql

Two new tables:

• cost_centers (user_id, code, name, is_active) with UNIQUE(user_id, code)
• projects (user_id, code, name, is_active, start_date, end_date) with UNIQUE(user_id, code)

Both with standard RLS and updated_at triggers.

Migration 16: Voucher Sequence Hardening

supabase/migrations/20240101000016_voucher_sequences.sql

New table voucher_sequences (user_id, fiscal_period_id, voucher_series, last_number) for tracking sequence state.

Replaced next_voucher_number() with concurrent-safe version using INSERT ON CONFLICT DO UPDATE RETURNING (row-level lock instead of MAX+1).

New DEFERRABLE constraint trigger check_balance_on_post validates debit==credit when an entry transitions from draft to posted.

New function detect_voucher_gaps(p_user_id, p_fiscal_period_id, p_series) returns gap ranges for compliance reporting.

Migration 17: Enforcement Triggers

supabase/migrations/20240101000017_enforcement_triggers.sql

8 trigger functions:

1. enforce_journal_entry_immutability() — allows draft→draft, draft→posted, posted→reversed. Blocks all other updates/deletes on committed entries.
2. enforce_journal_entry_line_immutability() — blocks modifications to lines of posted/reversed entries.
3. enforce_period_lock() — rejects journal_entries writes when is_closed=true OR locked_at IS NOT NULL.
4. enforce_period_lock_documents() — blocks document attachment to entries in locked periods.
5. block_document_deletion() — blocks deletion if linked to committed entry or within retention window. Logs blocked attempts to audit_log.
6. enforce_retention_journal_entries() — blocks journal entry deletion within 7-year retention window.
7. set_committed_at() — auto-sets committed_at = now() on draft→posted transition.
8. calculate_retention_expiry() — auto-sets retention_expires_at = period_end + 7 years. Backfills existing rows.

Migration 18: Audit Logging Triggers

supabase/migrations/20240101000018_audit_triggers.sql

SECURITY DEFINER function write_audit_log() that detects action type from TG_OP and state transitions (draft→posted = COMMIT, posted→reversed = REVERSE, locked_at set = LOCK_PERIOD, is_closed set = CLOSE_PERIOD). Captures old_state/new_state as JSONB.

AFTER triggers on: journal_entries, journal_entry_lines, chart_of_accounts, document_attachments, fiscal_periods, company_settings, tax_codes.

---

TypeScript Changes

Modified types in types/index.ts

Type	Change
JournalEntrySourceType	Added 'storno' | 'correction' | 'import' | 'system'
JournalEntry	Added committed_at, reversed_by_id, reverses_id, correction_of_id
JournalEntryLine	Added tax_code, cost_center, project
CreateJournalEntryLineInput	Added optional tax_code, cost_center, project
FiscalPeriod	Added locked_at, retention_expires_at
BASAccount	Added sru_code

New types added to types/index.ts

• TaxCode interface, TaxCodeId union type
• DocumentAttachment interface, DocumentUploadSource type, CreateDocumentAttachmentInput
• AuditLogEntry interface, AuditAction union type
• CostCenter interface
• Project interface
• VoucherGap interface

---

New Service Files

lib/core/audit/audit-service.ts

Read-only service (audit log is written by DB triggers):

• getAuditLog(userId, filters) — paginated query with action/table/date filters
• getEntityHistory(userId, tableName, recordId) — full mutation history of one record
• getCorrectionChain(userId, journalEntryId) — traces original→storno→corrected via linked IDs

lib/core/documents/document-service.ts

• uploadDocument(userId, file, metadata) — computes SHA-256 via Web Crypto, uploads to Supabase Storage, creates record
• createNewVersion(userId, originalId, file) — creates new version, marks old as superseded (WORM)
• linkToJournalEntry(userId, documentId, journalEntryId) — links document to entry
• verifyIntegrity(userId, documentId) — re-downloads, re-hashes, compares to stored hash

lib/core/tax/tax-code-service.ts

• getTaxCodes(userId) — returns user codes + system codes
• getTaxCodeByCode(userId, code) — single lookup, user code takes precedence
• calculateMomsFromTaxCodes(userId, periodStart, periodEnd) — sums journal lines by tax_code, maps to moms boxes via tax_codes table
• seedTaxCodes(userId) — calls seed_tax_codes_for_user RPC

lib/core/bookkeeping/storno-service.ts

• correctEntry(userId, originalEntryId, correctedLines) — 3-step correction:
  1. Creates storno entry with swapped debits/credits, source_type='storno', reverses_id set
  2. Creates corrected entry with new data, source_type='correction', correction_of_id set
  3. Marks original as reversed with reversed_by_id set
  4. Returns { reversal, corrected }

---

Modified Existing Files

lib/bookkeeping/engine.ts

• New buildLineInserts() helper that includes tax_code, cost_center, project in all line inserts
• New createDraftEntry(userId, input) — inserts as draft with voucher_number=0, no commit
• New commitEntry(userId, entryId) — assigns voucher number via next_voucher_number RPC, transitions to posted (DB triggers handle committed_at and balance validation)
• Existing createJournalEntry() kept as convenience wrapper (create + immediate commit)
• reverseEntry() rewritten: now sets reverses_id on the reversal entry, sets reversed_by_id on the original, uses source_type='storno', preserves dimensions on reversed lines

lib/reports/vat-declaration.ts

• Added TaxCode import
• New calculateVatDeclarationFromTaxCodes(userId, periodType, year, period) — generates momsdeklaration by querying journal_entry_lines grouped by tax_code, then mapping via tax_codes table to moms boxes
• Legacy calculateVatDeclaration() preserved for backward compatibility (invoice/transaction/receipt approach)

lib/reports/sie-export.ts

• Now fetches cost_centers and projects tables
• Outputs #DIM 1 "Kostnadsställe" and #DIM 6 "Projekt" dimension definitions
• Outputs #OBJEKT records for each cost center and project
• Outputs #SRU records from chart_of_accounts.sru_code after each #KONTO
• #TRANS lines now include dimension object lists: {1 "CC01" 6 "P01"} when cost_center/project are set

---

Verification

• npx tsc --noEmit passes with zero errors