boc/docs/arc/ARC-001-canonical-domain-model.md

ARC-001 — Canonical Domain Model

Status: Accepted
Datum: 2026-06-01
Beslutsfattare: AAMOS Architecture Team

---

Kontext

AAMOS är ett verksamhetsoperativsystem vars primära designkrav är att moduler (Ekonomi, CRM, HR, Projekt, Kvalitet, Inköp, Kontrakt) kan samexistera, utbyta data och bygga på varandras entiteter utan att skapa n×m-mappningsproblem.

Utan ett kanoniskt objektsystem uppstår ofrånkomligen:

• Semantisk drift — samma begrepp (t.ex. "Person") modelleras på 4 olika sätt i 4 moduler, vilket omöjliggör korsmodulärsökning och AI-kontext
• Integrationsskuld — varje ny modul måste skriva egna adaptrar mot alla befintliga moduler
• Auditbrist — när ett objekt existerar på flera ställen blir spårbarhet svårt att garantera

Ekonomimodulen är referensimplementationen. Alla val i detta ADR speglas redan (eller ska speglas) i Ekonomimodulens databasschema.

---

Beslut

AAMOS definierar tolv universella kanoniska objekt. Varje modul MÅSTE använda dessa objekt som primärreferenser och får inte definiera alternativa entiteter för samma semantiska koncept.

Fundamentala fält (alla objekt)

Varje kanoniskt objekt bär alltid dessa fält:

Fält	Typ	Beskrivning
id	UUID v7	Globalt unikt, tidsordnat
tenant_id	UUID	Isoleringsdomän (se ARC-003)
created_at	timestamptz	ISO 8601, UTC
updated_at	timestamptz	ISO 8601, UTC, auto-update
created_by	UUID	Referens till Person.id eller system-ID
deleted_at	timestamptz|null	Soft-delete, null = aktiv
metadata	jsonb	Fri nyckel-värde-extension (modul-specifika fält)
version	integer	Optimistic locking, inkrementeras vid varje UPDATE

UUID v7 används för att primary key-index förblir klusterordnade i PostgreSQL och förhindrar page splits vid hög insertfrekvens.

---

Objekt 1 — Entity

Abstrakt basobjekt. Alla övriga kanoniska objekt ärver Entity-kontraktet (de fundamentala fälten ovan). Entity instansieras aldrig direkt — det är ett kontrakt, inte en tabell.

Syfte: Definiera det minsta kontraktet som gör ett objekt spårbart, isolerat och versionerat.

Relationer:

• Varje konkret objekt implementerar Entity-kontraktet
• Entity-kontraktet gör det möjligt för generiska tjänster (audit, sök, event-routing) att hantera alla objekt uniformt

---

Objekt 2 — Organization

Bolag, juridisk person, koncern, avdelning, team, kostnadsställe.

Fält	Typ	Beskrivning
name	text	Officiellt namn
org_number	text|null	Organisationsnummer (landsspecifikt)
org_type	enum	company, department, team, group, subsidiary
parent_id	UUID|null	Självrefererande hierarki
country_code	char(2)	ISO 3166-1 alpha-2
tax_id	text|null	Momsregistreringsnummer
currency_code	char(3)	ISO 4217 (primärvaluta)
status	enum	active, inactive, merged, dissolved
external_refs	jsonb	{erp_id, crm_id, ...}

Relationer:

• Organization → Organization (parent_id, hierarkisk)
• Organization ↔ Person (many-to-many via memberships)
• Organization → Location (many)
• Organization → Contract (many)

Ekonomimodulen-mappning:
accounts.owner_org_id → Organization.id
journal_entries.entity_id → Organization.id (när motpart är bolag)

---

Objekt 3 — Person

Anställd, kontaktperson, ägare, kund, leverantörskontakt, systemanvändare.

Fält	Typ	Beskrivning
first_name	text
last_name	text
display_name	text	Beräknat eller angivet
email	text|null	Primär e-post
phone	text|null	E.164-format
national_id	encrypted_text|null	Personnummer — krypterat i vila
person_type	enum	employee, contact, customer, owner, system
primary_org_id	UUID|null	→ Organization.id
user_account_id	UUID|null	→ auth-systemets User.id
gdpr_consent	jsonb	Samtyckesregister per ändamål

Relationer:

• Person → Organization (many-to-many via memberships)
• Person → Location (many, adress-koppling)
• Person → Task (assignee)
• Person → Contract (signatory)

Ekonomimodulen-mappning:
suppliers.contact_person_id → Person.id
expense_reports.submitted_by → Person.id

---

Objekt 4 — Asset

Anläggningstillgång, resursobjekt, produkt, inventariepost, licenspost.

Fält	Typ	Beskrivning
name	text
asset_type	enum	fixed_asset, inventory, product, license, resource, intangible
serial_number	text|null
acquisition_date	date|null
acquisition_cost	numeric(18,4)|null
currency_code	char(3)|null
owner_org_id	UUID|null	→ Organization.id
location_id	UUID|null	→ Location.id
status	enum	active, disposed, under_maintenance, transferred
depreciation_policy	jsonb|null	Avskrivningsregler (Ekonomi)

Relationer:

• Asset → Organization (owner)
• Asset → Location (plats)
• Asset → Transaction (inköp, avskrivning)
• Asset → Contract (leasing, garanti)

Ekonomimodulen-mappning:
fixed_assets tabell är en direkt implementation av Asset med utökad depreciation_policy.

---

Objekt 5 — Location

Adress, arbetsplats, lagerplats, land, leveransadress.

Fält	Typ	Beskrivning
name	text|null	T.ex. "Huvudkontor Stockholm"
location_type	enum	address, workplace, warehouse, country, virtual
street	text|null
city	text|null
postal_code	text|null
country_code	char(2)	ISO 3166-1
region	text|null	Stat/landsdel
coordinates	point|null	PostGIS POINT(lon lat)
parent_id	UUID|null	Hierarki (land → stad → adress)

Relationer:

• Location → Organization (many)
• Location → Person (hemadress, arbetsplats)
• Location → Asset (plats)

---

Objekt 6 — Project

Projekt, uppdrag, kostnadsbärare, kampanj, budgetpost.

Fält	Typ	Beskrivning
name	text
code	text|null	Projektnamn/nummer för referens
project_type	enum	internal, client, rnd, infrastructure, overhead
status	enum	planning, active, on_hold, completed, cancelled
owner_id	UUID	→ Person.id
org_id	UUID	→ Organization.id
budget	numeric(18,4)|null
currency_code	char(3)|null
start_date	date|null
end_date	date|null
parent_project_id	UUID|null	Delprojekt-hierarki

Relationer:

• Project → Organization (ägande)
• Project → Person (projektledare, team)
• Project → Task (nedbrytning)
• Project → Transaction (kostnader, intäkter)
• Project → Contract (kontrakt kopplade till projekt)

Ekonomimodulen-mappning:
cost_centers.project_id → Project.id
budget_lines.project_id → Project.id

---

Objekt 7 — Task

Arbetsuppgift, aktivitet, ärende, batchjobb, processuppgift.

Fält	Typ	Beskrivning
title	text
description	text|null
task_type	enum	manual, automated, approval, review, notification
status	enum	pending, in_progress, blocked, completed, cancelled
priority	enum	low, medium, high, critical
assignee_id	UUID|null	→ Person.id
project_id	UUID|null	→ Project.id
parent_task_id	UUID|null	Subtask-hierarki
due_date	timestamptz|null
completed_at	timestamptz|null
workflow_instance_id	UUID|null	→ Workflow.id

Relationer:

• Task → Person (assignee, creator)
• Task → Project (tillhörighet)
• Task → Workflow (processdrivet)
• Task → Document (bilagor)

---

Objekt 8 — Workflow

Processinstans. Kopplas till Workflow Engine (framtida).

Fält	Typ	Beskrivning
workflow_definition_id	text	Referens till process-definition
workflow_version	text	Versionerad processdefinition
status	enum	pending, running, waiting, completed, failed, cancelled
context	jsonb	Runtime-kontext för processinstansen
started_at	timestamptz|null
completed_at	timestamptz|null
initiator_id	UUID	→ Person.id eller system
current_step	text|null	Stegidentifierare

Relationer:

• Workflow → Task (genererade uppgifter)
• Workflow → Document (processade dokument)
• Workflow → Transaction (utlösta transaktioner)

Ekonomimodulen-mappning:
Fakturaflöde (inkommen faktura → godkännande → betalning) är en Workflow-instans.

---

Objekt 9 — Document

Faktura, kvitto, kontrakt, rapport, fil, attest.

Fält	Typ	Beskrivning
title	text
document_type	enum	invoice, receipt, contract, report, attachment, specification, certificate
mime_type	text|null	application/pdf, image/jpeg, etc.
storage_key	text|null	S3/blob-sökväg
checksum	text|null	SHA-256 av filinnehållet
size_bytes	bigint|null
source_system	text|null	Ursprungssystem
related_entity_id	UUID|null	Polymorf referens
related_entity_type	text|null	T.ex. Transaction, Contract
classification	enum	public, internal, confidential, restricted (se ARC-003)
extracted_data	jsonb|null	AI-extraherade fält (se ARC-002)

Relationer:

• Document → Transaction (underlag)
• Document → Contract (kontraktsdokument)
• Document → Workflow (processunderlag)

Ekonomimodulen-mappning:
supplier_invoices.document_id → Document.id
expense_reports.receipt_document_ids → Document.id[]

---

Objekt 10 — Transaction

Ekonomisk händelse. JournalEntry är en Transaction med transaction_type = journal_entry.

Fält	Typ	Beskrivning
transaction_type	enum	journal_entry, payment, invoice, credit_note, accrual, depreciation, transfer
amount	numeric(18,4)	Absolutbelopp
currency_code	char(3)	ISO 4217
base_currency_amount	numeric(18,4)|null	Omräknat till baskvaluta
exchange_rate	numeric(12,8)|null
status	enum	draft, posted, voided, pending_approval
transaction_date	date	Transaktionsdatum (affärsdatum)
value_date	date|null	Valuteringsdatum
reference	text|null	Externt referensnummer
counterparty_id	UUID|null	→ Organization.id eller Person.id
project_id	UUID|null	→ Project.id
document_id	UUID|null	→ Document.id (underlag)
lines	jsonb	Transaktionsrader med konton och belopp

Relationer:

• Transaction → Organization (motpart)
• Transaction → Person (utförare)
• Transaction → Document (verifikat)
• Transaction → Project (kostnadsbärare)
• Transaction → Asset (anläggningstillgångsrörelser)

Ekonomimodulen-mappning:
journal_entries är Transactions med transaction_type = journal_entry.
Ledger Engine håller transaktionsrader i lines-jsonb eller separata rader beroende på volym.

---

Objekt 11 — Event

Systemevent, domänevent. Detta är Hermes Event Fabric-payloaden.

Fält	Typ	Beskrivning
event_type	text	Namnrymd: aamos.ekonomi.transaction.posted
event_version	text	Semver av event-schemat
source_service	text	Originerande tjänst
correlation_id	UUID	Spårnings-ID genom systemet
causation_id	UUID|null	ID på det event som orsakade detta
subject_type	text	Typ av ämnesobjekt
subject_id	UUID	ID på ämnesobjektet
payload	jsonb	Eventnyttolast
published_at	timestamptz	Publiceringstidpunkt

Namnrymdskonvention:
aamos.<modul>.<objekt>.<verb> — t.ex. aamos.ekonomi.transaction.posted, aamos.crm.contact.created

Relationer:

• Event refererar till vilket som helst kanoniskt objekt via subject_id
• Events persisteras i JSONL-fallback för replay

---

Objekt 12 — Contract

Avtal, SLA, leverantörsavtal, anställningsavtal, ramavtal, licens.

Fält	Typ	Beskrivning
title	text
contract_type	enum	supplier, customer, employment, sla, license, framework, nda
status	enum	draft, pending_signature, active, expired, terminated, renewed
counterparty_org_id	UUID|null	→ Organization.id
counterparty_person_id	UUID|null	→ Person.id
owner_org_id	UUID	→ Organization.id (intern part)
start_date	date|null
end_date	date|null
auto_renewal	boolean
value	numeric(18,4)|null	Kontraktsvärde
currency_code	char(3)|null
document_id	UUID|null	→ Document.id (signerat PDF)
terms	jsonb|null	Strukturerade avtalsvillkor

Relationer:

• Contract → Organization (parter)
• Contract → Person (signatärer)
• Contract → Document (kontraktsdokument)
• Contract → Transaction (betalningsplan, fakturor)
• Contract → Asset (leasade tillgångar)

---

Ekonomimodulens fullständiga mappning

Ekonomimodul          → Kanonisk typ
──────────────────────────────────────────
JournalEntry          → Transaction (type=journal_entry)
Supplier              → Organization (org_type=company)
Customer              → Organization (org_type=company)
SupplierInvoice       → Document (type=invoice) + Transaction
ExpenseReport         → Document (type=report) + Transaction[]
FixedAsset            → Asset (type=fixed_asset)
CostCenter            → Project (type=overhead/internal)
Employee              → Person (type=employee)
ApprovalFlow          → Workflow
Receipt               → Document (type=receipt)
SupplierContract      → Contract (type=supplier)

---

Konsekvenser

Positiva

• Ny modul definierar bara sina egna extensions i metadata, inte nya bastyper
• AI-kontextfönster kan laddas med enhetliga objektrepresentationer
• Korsmodulär sökning och audit fungerar utan adaptrar
• Event-routing är självbeskrivande via subject_type

Negativa / risker

• Migrationsarbete: Ekonomimodulen måste verifiera att befintliga tabeller uppfyller kontraktet
• UUID v7 kräver att databasen kan generera dem (pgcrypto eller app-sida)
• metadata jsonb kan bli en dumpingsplats — kräver disciplin och review

---

Implementation

Fas 1 (Ekonomimodulen, nu)

1. Verifiera att alla tabeller har tenant_id, version, deleted_at
2. Lägg till metadata jsonb DEFAULT '{}' på tabeller som saknar det
3. Dokumentera mappning i modulens README

Fas 2 (inför CRM)

1. Skapa dedikerade tabeller för Organization och Person i core-schema
2. Ekonomimodulen FK:ar till core.organizations och core.persons

Fas 3 (plattformsnivå)

1. GraphQL/REST-lager för kanoniska objekt
2. Unified search-index över alla objekt
3. AI-kontext-builder som hämtar kanonisk representation

---

Öppna frågor

1. Ska kanoniska objekt bo i ett delat core-schema eller replikeras per modul?
   Förslag: Shared schema för Person, Organization, Location. Replika med CDC för moduler som behöver hög läsprestanda.

2. UUID v7 vs ULID?
   UUID v7 är nu RFC-standard och stöds bättre i PostgreSQL-ekosystemet. ULID är alternativ om befintlig kod är svår att migrera.

3. metadata-schemavalidering?
   Modul-specifika JSON Schema-fragment bör definieras och valideras vid INSERT/UPDATE.

4. Event-schema-registret?
   Hermes bör ha ett schema-register som validerar event-payloads mot event_version. Se ARC-002.