Notizarr/docs/phase1/03-database-model.md

03 — Database Model (PostgreSQL 16)

Conventions: id uuid primary key default gen_random_uuid() (needs pgcrypto or use uuid-ossp's uuid_generate_v4() — Drizzle migration will enable pgcrypto), all timestamps timestamptz, stored/compared in UTC. Migrations managed by drizzle-kit (plain SQL files checked into the repo).

users

column	type	notes
id	uuid pk
email	text unique not null
display_name	text not null
avatar_url	text null
role	text not null default 'user'	check in ('admin','user')
auth_subject	text not null	OIDC sub, or the proxy-auth identity string
auth_issuer	text null	OIDC issuer URL, null for proxy mode
created_at	timestamptz default now()
updated_at	timestamptz default now()
last_login_at	timestamptz null

Unique index on (auth_issuer, auth_subject).

topics

column	type	notes
id	uuid pk
slug	text unique not null	URL/publish-path identifier, e.g. homeassistant
display_name	text not null
description	text null
icon	text null	icon key or emoji
accent_color	text null	hex
retention_days	int null	null = use global default; 0 = forever
restricted	boolean not null default false	if true, visibility gated by topic_members
created_by	uuid fk users(id) null
created_at	timestamptz default now()
updated_at	timestamptz default now()
archived_at	timestamptz null	soft delete

topic_members

Only consulted when topics.restricted = true.

column	type
topic_id	uuid fk topics(id)
user_id	uuid fk users(id)

Primary key (topic_id, user_id).

user_topic_subscriptions

Per-user push preference for a topic. Absence of a row = default push_enabled = true for any topic the user can see (avoids needing to backfill a row per user per topic on topic creation).

column	type	notes
id	uuid pk
user_id	uuid fk users(id)
topic_id	uuid fk topics(id)
push_enabled	boolean not null default true
created_at	timestamptz default now()
updated_at	timestamptz default now()

Unique (user_id, topic_id).

notifications

column	type	notes
id	uuid pk
topic_id	uuid fk topics(id) not null
source	text not null	free-form publisher-supplied service name
title	text not null
message	text not null
external_url	text null	"click" URL, browser-rendered only
image_url	text null	browser-rendered only, never server-fetched
attachment_filename	text null	metadata only
attachment_content_type	text null	metadata only
attachment_size_bytes	bigint null	metadata only
deduplication_key	text null
occurrence_count	int not null default 1	incremented on deduped repeats
raw_priority	text null	ntfy-compat passthrough, never read for logic
sender_token_id	uuid fk api_tokens(id) null
search_vector	tsvector generated	to_tsvector('simple', title || ' ' || message), GIN indexed
created_at	timestamptz default now()	= "received_at" (server receipt time)
updated_at	timestamptz default now()	bumped when occurrence_count increments

Indexes:

• (topic_id, created_at desc) — topic history pagination
• (deduplication_key, topic_id, created_at desc) where deduplication_key is not null — dedupe window lookups
• GIN (search_vector) — full-text search
• (created_at) — retention cleanup sweep

user_notification_state

Per-user read/star state (notifications are shared rows across all users who can see the topic).

column	type	notes
id	uuid pk
user_id	uuid fk users(id)
notification_id	uuid fk notifications(id)
read	boolean not null default false
read_at	timestamptz null
starred	boolean not null default false
starred_at	timestamptz null

Unique (user_id, notification_id). Indexes on (user_id, read), (user_id, starred) for unread-count and starred-list queries.

push_subscriptions

column	type	notes
id	uuid pk
user_id	uuid fk users(id)
endpoint	text unique not null	Push service subscription URL
p256dh	text not null
auth	text not null
user_agent	text null
device_label	text null	auto-derived from UA, user-editable
created_at	timestamptz default now()
last_seen_at	timestamptz default now()	bumped on each successful push or resubscribe
disabled_at	timestamptz null	set after push service returns 404/410

api_tokens

column	type	notes
id	uuid pk
name	text not null	e.g. "Home Assistant"
token_hash	text unique not null	SHA-256 hex of the full token
token_prefix	text not null	first 8 chars after nzr_, for display
allowed_source	text null	if set, publisher's source must match
allowed_cidrs	text[] null	null = no IP restriction beyond INGESTION_ALLOWED_CIDRS
expires_at	timestamptz null
revoked_at	timestamptz null
created_by	uuid fk users(id)
created_at	timestamptz default now()
last_used_at	timestamptz null
usage_count	bigint not null default 0

api_token_topics

Join table: which topics a token may publish to (empty = all topics).

column	type
token_id	uuid fk api_tokens(id)
topic_id	uuid fk topics(id)

Primary key (token_id, topic_id).

push_delivery_attempts

column	type	notes
id	uuid pk
notification_id	uuid fk notifications(id)
push_subscription_id	uuid fk push_subscriptions(id)
status	text not null	enum: pending, accepted_by_push_service, failed, invalid_subscription, expired
http_status	int null
error_message	text null	sanitized (no PII/secrets)
retry_count	int not null default 0
attempted_at	timestamptz default now()

Index (notification_id), (push_subscription_id, attempted_at desc).

audit_log

column	type	notes
id	uuid pk
actor_user_id	uuid fk users(id) null
actor_token_id	uuid fk api_tokens(id) null
action	text not null	e.g. topic.create, token.revoke, rate_limit.rejected, user.role_change
target_type	text null
target_id	text null
metadata	jsonb null
ip_address	inet null
created_at	timestamptz default now()

Index (created_at desc), (action).

system_settings

Singleton key/value store — VAPID keys, global retention default, rate-limit config overrides.

column	type
key	text primary key
value	jsonb not null
updated_at	timestamptz default now()

Known keys: vapid_keys ({publicKey, privateKey, generatedAt}), retention_default_days, rate_limit_overrides.

Retention cleanup

An interval job (every 1h) deletes notifications rows older than the effective retention (topics.retention_days, falling back to system_settings.retention_default_days, default 90). retention_days = 0 means "forever" and is skipped. Cascade deletes remove associated user_notification_state and push_delivery_attempts rows (ON DELETE CASCADE on the FKs).