Files

T

Jannis Braun a3a7527c9e chore: add system docs, specs, and misc updates from other sessions

- Add complete docs/systems/ reference (18 system docs)
- Add federation relay status doc and prior spec/plan docs
- Remove superseded docs/federation-dm-s2s.md (replaced by docs/systems/federation.md)
- CLAUDE.md updates
- Minor fixes in social.ts, types.ts, AddDmMemberModal, NewDmModal, UserSettings

2026-03-31 03:40:34 +02:00

14 KiB

Raw Blame History

Database Schema Reference

Source of truth: packages/server/src/db/schema.ts (Drizzle ORM) Migrations: packages/server/src/db/migrate.ts (runs on startup via runMigrations()) Engine: SQLite via better-sqlite3 IDs: Snowflake text, permissions: bigint decimal strings

Core Tables

users

Column	Type	Default	Notes
id	text PK		Snowflake
username	text UNIQUE NOT NULL		Login name
displayName	text
passwordHash	text NOT NULL		bcrypt; `'!federation-replicated'` for stubs
avatar	text		Upload filename
status	text	`'offline'`	online/idle/dnd/offline
customStatus	text
isAdmin	integer	0	First registered user = 1
homeInstance	text		Federation origin URL (null = local)
homeUserId	text		Canonical ID on home instance
replicatedInstances	text	`'[]'`	JSON array of instance URLs
banner	text		Upload filename
accentColor	text		Hex color
avatarColor	text		Hex color
bio	text
isDeleted	integer	0	Soft-delete flag
discoverable	integer	1	Visible in user directory
profileUpdatedAt	integer		Epoch ms
passwordChangedAt	integer		Token revocation: tokens before this rejected
showActivity	integer NOT NULL	1	Rich presence visibility
createdAt	integer NOT NULL		Epoch ms

spaces

Column	Type	Default	Notes
id	text PK
name	text NOT NULL
icon	text		Upload filename
banner	text		Upload filename
avatarColor	text		Hex color
ownerId	text NOT NULL		FK → users.id
inviteCode	text UNIQUE
visibility	text	`'private'`	public/request/private
description	text
createdAt	integer NOT NULL

space_members

PK: (spaceId, userId)

Column	Type	Notes
spaceId	text NOT NULL	FK → spaces.id CASCADE
userId	text NOT NULL	FK → users.id CASCADE
nickname	text	Per-space display name
joinedAt	integer NOT NULL

channel_categories

Column	Type	Default	Notes
id	text PK
spaceId	text NOT NULL		FK → spaces.id CASCADE
name	text NOT NULL
position	integer	0
createdAt	integer NOT NULL

channels

Column	Type	Default	Notes
id	text PK
spaceId	text NOT NULL		FK → spaces.id CASCADE
name	text NOT NULL
type	text NOT NULL		text/voice
topic	text
position	integer	0
categoryId	text		Soft FK → channel_categories
createdAt	integer NOT NULL

messages

Column	Type	Notes
id	text PK
channelId	text NOT NULL	FK → channels.id CASCADE
userId	text NOT NULL	FK → users.id
replyToId	text	FK → messages.id SET NULL
content	text
editedAt	integer
createdAt	integer NOT NULL

attachments

Column	Type	Notes
id	text PK
messageId	text	FK → messages.id CASCADE
dmMessageId	text	FK → dm_messages.id CASCADE
uploaderId	text	User who uploaded
filename	text NOT NULL	Stored filename
originalName	text NOT NULL	User-facing name
mimetype	text NOT NULL
size	integer NOT NULL	Bytes
thumbnailFilename	text	Generated thumbnail
width	integer	Image/video pixel width
height	integer	Image/video pixel height
duration	real	Audio/video seconds
sourceUrl	text	Remote URL (federation)
federationStatus	text	local/remote/remote_partial
federationMeta	text	JSON rejection info
createdAt	integer NOT NULL
CHECK: exactly one of messageId/dmMessageId is set

embeds

Column	Type	Notes
id	text PK
messageId	text	FK → messages.id CASCADE
dmMessageId	text	FK → dm_messages.id CASCADE
url	text NOT NULL
embedType	text NOT NULL	generic/video/image/audio/rich
provider	text	youtube/vimeo/spotify/null
title	text
description	text
image	text	Thumbnail/og:image URL
embedUrl	text	iframe-safe URL
width	integer
height	integer
color	text
createdAt	integer NOT NULL
CHECK: exactly one of messageId/dmMessageId is set

reactions

PK: id

Column	Type	Notes
id	text PK
messageId	text NOT NULL	FK → messages.id CASCADE
userId	text NOT NULL	FK → users.id CASCADE
emoji	text NOT NULL
createdAt	integer NOT NULL

DM Tables

dm_channels

Column	Type	Notes
id	text PK
ownerId	text	NULL for 1-on-1, set for group
federatedId	text	Cross-instance identifier
ownerHomeUserId	text	Owner's canonical home ID
ownerHomeInstance	text	Owner's home instance URL
deletedAt	integer	Soft-delete (GC after 24h if no local members)
createdAt	integer NOT NULL

dm_members

PK: (dmChannelId, userId)

Column	Type	Default	Notes
dmChannelId	text NOT NULL		FK → dm_channels.id CASCADE
userId	text NOT NULL		FK → users.id CASCADE
closed	integer	0	Soft-close flag

dm_messages

Column	Type	Default	Notes
id	text PK
dmChannelId	text NOT NULL		FK → dm_channels.id CASCADE
userId	text NOT NULL		FK → users.id
replyToId	text		FK → dm_messages.id SET NULL
content	text
type	text NOT NULL	`'user'`	user/system
editedAt	integer
sourceInstance	text		Federation source origin
sourceMessageId	text		Original ID on source instance
encryptionVersion	integer	0
createdAt	integer NOT NULL

dm_reactions

PK: id

Column	Type	Notes
id	text PK
dmMessageId	text NOT NULL	FK → dm_messages.id CASCADE
userId	text NOT NULL	FK → users.id CASCADE
emoji	text NOT NULL
createdAt	integer NOT NULL

friends

PK: (userId, friendId)

Column	Type	Notes
userId	text NOT NULL	FK → users.id CASCADE
friendId	text NOT NULL	FK → users.id CASCADE
createdAt	integer NOT NULL

friend_requests

Column	Type	Default	Notes
id	text PK
fromId	text NOT NULL		FK → users.id CASCADE
toId	text NOT NULL		FK → users.id CASCADE
status	text	`'pending'`	pending/accepted/declined
createdAt	integer NOT NULL

RBAC Tables

roles

Column	Type	Default	Notes
id	text PK
spaceId	text NOT NULL		FK → spaces.id CASCADE
name	text NOT NULL
color	text	`'#b9bbbe'`	Hex
position	integer	0	Hierarchy position
permissions	text		Bigint decimal string
createdAt	integer NOT NULL

member_roles

PK: (spaceId, userId, roleId) All columns FK CASCADE to their respective tables.

channel_overrides

PK: (channelId, targetType, targetId)

Column	Type	Default	Notes
channelId	text NOT NULL		FK → channels.id CASCADE
targetType	text NOT NULL		role/member
targetId	text NOT NULL		Role ID or user ID
allow	text NOT NULL	`'0'`	Bigint decimal string
deny	text NOT NULL	`'0'`	Bigint decimal string

category_overrides

PK: (categoryId, targetType, targetId) Same structure as channel_overrides, with categoryId FK → channel_categories.id CASCADE.

State Tables

read_states

PK: (userId, channelId)

Column	Type	Notes
userId	text NOT NULL	FK → users.id CASCADE
channelId	text NOT NULL	Channel or DM channel ID
lastReadMessageId	text NOT NULL
updatedAt	integer NOT NULL

space_folders

Column	Type	Default	Notes
id	text PK
userId	text NOT NULL		FK → users.id CASCADE
name	text
color	text
position	integer	0
createdAt	integer NOT NULL

space_folder_members

PK: (folderId, spaceId)

Column	Type	Default	Notes
folderId	text NOT NULL		FK → space_folders.id CASCADE
spaceId	text NOT NULL		May be federated (no local FK)
position	integer	0

user_space_layout

PK: userId

Column	Type	Default	Notes
userId	text PK		FK → users.id CASCADE
layout	text NOT NULL	`'[]'`	JSON array of {t:'s',id}
updatedAt	integer NOT NULL

Moderation Tables

bans