Domain subsystem designs
The mxd reference set documents three major domain subsystems in depth: file services, chat and presence, and threaded news. These designs shape the database schema, the verification invariants, and the transaction catalogue that the rest of the site references.
All three subsystems carry a Planned badge. The models are designed and documented; their broader runtime wiring is roadmap work.
File services
Planned
The file subsystem separates content storage from metadata
management. An object-store abstraction backed by the
object_store
crate handles binary content on local disk, S3, or Azure, while
the database owns the hierarchical folder structure, permissions,
and file metadata through a unified
FileNode
table.
Object store
Flat key-value storage for file content. Local filesystem,
S3, and Azure backends are supported through the
object_store
crate. Files are addressed by opaque keys; the
hierarchical path lives only in the database.
FileNode metadata
A unified
FileNode
table models files, folders, and aliases in a single
hierarchy. Each node carries a type discriminator,
optional
object_key,
parent reference, comment field, and creation metadata.
Transaction catalogue
List files and folders in a directory path.
Stream file content to the client. Supports resumable transfers using the file length as an offset.
Receive file content from the client. Partial uploads are kept with a database entry marked incomplete; resume uses the file length as an offset.
Remove a file node and its object-store content.
Create a folder node in the hierarchy.
Read and update file metadata including comments.
Relocate a file or folder within the hierarchy.
Create a
FileNode
of type alias pointing to a target node, with no own
object_key.
Recursive folder transfer in both directions.
Drop boxes:
Folders with
is_dropbox=true
are write-only for regular users. Uploads succeed, but list
requests return empty results for unprivileged sessions.
Privilege bits 28 and 29 control folder and file comment
visibility.
ACL model:
Per-file and per-folder access control uses a
Permission
table linking principals to resources. The flat object-store
keys are invisible to the ACL layer; permissions apply to the
hierarchical
FileNode
tree.
Chat and presence
PlannedThe chat subsystem models public lobbies, private group chats, and direct messages through a unified room-based schema. Presence notifications are tied to authenticated sessions and broadcast on login and logout.
Schema tables
id,
creator_id,
subject,
is_private,
created_at.
Public rooms use
is_private=false
and auto-join on login.
Join table linking users to rooms. Membership is added on room creation, invite acceptance, or public lobby auto-join.
Optional history persistence for chat rooms. Messages reference the room and sender with a timestamp.
Tracks pending, accepted, and declined invitations for private and group chats.
Invite and join flow
Invite (transaction 112)
Creator sends an invite to a user, creating a private or group room if one does not already exist.
Accept (transaction 113)
Accepting adds the user to the room's participant list and notifies existing members.
Decline (transaction 114)
Declining removes the invite record and notifies the room creator.
Chat subjects are set via transaction 120 (Set Chat Subject), which triggers a Notify Chat Subject (119) push to all room participants. Direct messages are modelled as private chats between exactly two participants — no separate DM table or transport path.
Presence: Presence uses transactions 300 (request user list), 301 (notify add user), and 302 (notify remove user). The server broadcasts add and remove notifications on authenticated login and logout. Presence state is transient — it is not persisted in the database.
News hierarchy
Planned
The news subsystem implements a three-level hierarchy: bundles
contain categories, which contain threaded articles. Bundles
support recursive nesting via a
parent_bundle_id
self-reference. Categories may live inside a bundle or at the top
level when
bundle_id IS NULL.
Hierarchy structure
Top-level grouping. Recursive nesting via
parent_bundle_id.
Topic containers inside bundles. May also exist at the top level.
Threaded content with linked-list navigation pointers.
Article pointer fields
The article this one replies to, establishing thread depth.
Previous sibling in the linked list at the same depth.
Next sibling in the linked list at the same depth.
Head of the child linked list — the first reply to this article.
Each article carries metadata fields:
title,
poster,
posted_at,
flags,
data_flavor,
and
data.
News permissions use 38 privilege codes modelled as a lookup table
with many-to-many linking between principals and resources.
Recursive CTE traversal: Navigating the bundle and article hierarchies requires recursive common table expressions. This is the primary reason the configuration page requires recursive CTE support from both SQLite and PostgreSQL.