From 67b507f4bd3c01a3fbbd298c9d51b9b1037ec54e Mon Sep 17 00:00:00 2001
From: mstar <me@mstar.dev>
Date: Thu, 27 Mar 2025 10:45:57 +0100
Subject: [PATCH] Describe all types for the new storage system

---
 storage-new/migrations.go                      |  8 ++++----
 storage-new/models/Emote.go                    | 10 +++++++---
 storage-new/models/MediaMetadata.go            |  3 +++
 storage-new/models/Note.go                     |  5 ++++-
 storage-new/models/NoteAccessLevelType.go      |  1 +
 storage-new/models/NoteToAttachments.go        |  1 +
 storage-new/models/NoteToEmotes.go             |  1 +
 storage-new/models/NoteToPing.go               |  1 +
 storage-new/models/NoteToTag.go                |  1 +
 storage-new/models/Reaction.go                 |  1 +
 storage-new/models/RemoteServer.go             |  2 ++
 storage-new/models/RemoteServerSoftwareType.go |  1 +
 storage-new/models/User.go                     |  3 +++
 storage-new/models/UserAuthentication.go       |  5 +++++
 storage-new/models/UserAuthenticationMethod.go |  1 +
 storage-new/models/UserBeingType.go            |  3 +++
 storage-new/models/UserBeings.go               |  4 +++-
 storage-new/models/UserInfoField.go            |  4 ++++
 storage-new/models/UserRelation.go             |  9 ---------
 storage-new/models/UserRelationType.go         |  1 +
 storage-new/models/UserRemote.go               |  1 +
 storage-new/models/UserRoles.go                |  8 --------
 storage-new/models/UserTags.go                 |  4 +++-
 storage-new/models/UserToRole.go               | 11 +++++++++++
 storage-new/models/UserToUserRelation.go       | 12 ++++++++++++
 25 files changed, 74 insertions(+), 27 deletions(-)
 delete mode 100644 storage-new/models/UserRelation.go
 delete mode 100644 storage-new/models/UserRoles.go
 create mode 100644 storage-new/models/UserToRole.go
 create mode 100644 storage-new/models/UserToUserRelation.go

diff --git a/storage-new/migrations.go b/storage-new/migrations.go
index 059757c..5faa9f5 100644
--- a/storage-new/migrations.go
+++ b/storage-new/migrations.go
@@ -45,12 +45,12 @@ func migrateTypes(db *gorm.DB) error {
 		&models.Role{},
 		&models.User{},
 		&models.UserAuthMethod{},
-		&models.UserBeings{},
+		&models.UserToBeing{},
 		&models.UserInfoField{},
-		&models.UserRelation{},
+		&models.UserToUserRelation{},
 		&models.UserRemoteLinks{},
-		&models.UserRole{},
-		&models.UserTag{},
+		&models.UserToRole{},
+		&models.UserToTag{},
 	); err != nil {
 		return err
 	}
diff --git a/storage-new/models/Emote.go b/storage-new/models/Emote.go
index 3e28ff9..f94ce34 100644
--- a/storage-new/models/Emote.go
+++ b/storage-new/models/Emote.go
@@ -2,11 +2,15 @@ package models
 
 import "gorm.io/gorm"
 
+// An emote is effectively an assignment of a name and server
 type Emote struct {
 	gorm.Model
-	// Metadata   MediaMetadata // `gorm:"foreignKey:MetadataId"`
+	// Media used for this emote
+	Metadata   MediaMetadata // `gorm:"foreignKey:MetadataId"`
 	MetadataId string
-	Name       string
-	// Server     RemoteServer // `gorm:"foreignKey:ServerId;references:ID"`
+	// Name of the emote. Also the text for using it in a message (ex. :bob:)
+	Name string
+	// Server the emote is from
+	Server   RemoteServer // `gorm:"foreignKey:ServerId;references:ID"`
 	ServerId uint
 }
diff --git a/storage-new/models/MediaMetadata.go b/storage-new/models/MediaMetadata.go
index a411c81..c75ee64 100644
--- a/storage-new/models/MediaMetadata.go
+++ b/storage-new/models/MediaMetadata.go
@@ -6,6 +6,9 @@ import (
 	"gorm.io/gorm"
 )
 
+// Metadata for describing some media
+// Media is, at least for Linstrom, always stored on a separate server,
+// be that the remote server it originated from or an s3 bucket
 type MediaMetadata struct {
 	ID        string    `gorm:"primarykey"` // The unique ID of this media file
 	CreatedAt time.Time // When this entry was created
diff --git a/storage-new/models/Note.go b/storage-new/models/Note.go
index 631a0cb..f0d6df9 100644
--- a/storage-new/models/Note.go
+++ b/storage-new/models/Note.go
@@ -6,7 +6,10 @@ import (
 	"gorm.io/gorm"
 )
 
-// Data defined in extra structs:
+// User created content, containing some message, maybe attachments,
+// tags, pings or other extra things
+//
+// Data defined in extra structs (links are included at the bottom):
 // - Attachments: models.NoteToAttachment
 // - Emotes: models.NoteToEmote
 // - Pings: models.NoteToPing
diff --git a/storage-new/models/NoteAccessLevelType.go b/storage-new/models/NoteAccessLevelType.go
index 15a725f..b023675 100644
--- a/storage-new/models/NoteAccessLevelType.go
+++ b/storage-new/models/NoteAccessLevelType.go
@@ -2,6 +2,7 @@ package models
 
 import "database/sql/driver"
 
+// The access level required to view a note
 type NoteAccessLevel uint8
 
 const (
diff --git a/storage-new/models/NoteToAttachments.go b/storage-new/models/NoteToAttachments.go
index 13ef7fb..21dd416 100644
--- a/storage-new/models/NoteToAttachments.go
+++ b/storage-new/models/NoteToAttachments.go
@@ -1,5 +1,6 @@
 package models
 
+// A binding of one note to one media attachment
 type NoteToAttachment struct {
 	Note         Note
 	NoteId       string
diff --git a/storage-new/models/NoteToEmotes.go b/storage-new/models/NoteToEmotes.go
index 70ce207..b218670 100644
--- a/storage-new/models/NoteToEmotes.go
+++ b/storage-new/models/NoteToEmotes.go
@@ -1,5 +1,6 @@
 package models
 
+// A binding of one note to one emote
 type NoteToEmote struct {
 	Note    Note
 	NoteId  string
diff --git a/storage-new/models/NoteToPing.go b/storage-new/models/NoteToPing.go
index 582a598..f7d1de8 100644
--- a/storage-new/models/NoteToPing.go
+++ b/storage-new/models/NoteToPing.go
@@ -1,5 +1,6 @@
 package models
 
+// A binding of one note to one mentioned account
 type NoteToPing struct {
 	Note         Note
 	NoteId       string
diff --git a/storage-new/models/NoteToTag.go b/storage-new/models/NoteToTag.go
index cf1fa87..33bee5d 100644
--- a/storage-new/models/NoteToTag.go
+++ b/storage-new/models/NoteToTag.go
@@ -1,5 +1,6 @@
 package models
 
+// A binding of one note to one string (hash)tag
 type NoteTag struct {
 	Note   Note
 	NoteId string
diff --git a/storage-new/models/Reaction.go b/storage-new/models/Reaction.go
index 021f6a7..aefe3ba 100644
--- a/storage-new/models/Reaction.go
+++ b/storage-new/models/Reaction.go
@@ -2,6 +2,7 @@ package models
 
 import "gorm.io/gorm"
 
+// A binding of one note to one account reacting to it with one emote
 type Reaction struct {
 	gorm.Model
 	Note      Note
diff --git a/storage-new/models/RemoteServer.go b/storage-new/models/RemoteServer.go
index af063ed..6324697 100644
--- a/storage-new/models/RemoteServer.go
+++ b/storage-new/models/RemoteServer.go
@@ -2,6 +2,8 @@ package models
 
 import "gorm.io/gorm"
 
+// RemoteServer describes an ActivityPub server
+// This includes self too
 type RemoteServer struct {
 	gorm.Model
 	ServerType ServerSoftwareType // What software the server is running. Useful for formatting
diff --git a/storage-new/models/RemoteServerSoftwareType.go b/storage-new/models/RemoteServerSoftwareType.go
index f0834f2..430b2ed 100644
--- a/storage-new/models/RemoteServerSoftwareType.go
+++ b/storage-new/models/RemoteServerSoftwareType.go
@@ -4,6 +4,7 @@ import (
 	"database/sql/driver"
 )
 
+// The software a server is running
 type ServerSoftwareType string
 
 const (
diff --git a/storage-new/models/User.go b/storage-new/models/User.go
index 80853a9..250cd11 100644
--- a/storage-new/models/User.go
+++ b/storage-new/models/User.go
@@ -6,6 +6,9 @@ import (
 	"gorm.io/gorm"
 )
 
+// A user describes an account for creating content.
+// This may be controlled by either a human or some external script
+//
 // Data stored in external types:
 // - Custom info fields
 // - Being types
diff --git a/storage-new/models/UserAuthentication.go b/storage-new/models/UserAuthentication.go
index 8c27b1e..cbca796 100644
--- a/storage-new/models/UserAuthentication.go
+++ b/storage-new/models/UserAuthentication.go
@@ -1,5 +1,10 @@
 package models
 
+// One authentication method linked to one account.
+// Contains the method and whatever the token may be
+// For a password, this would be a hash of that password,
+// totp would be the seed,
+// and passkey would be the webauthn.Credential, marshalled into json
 type UserAuthMethod struct {
 	User       User
 	UserId     string
diff --git a/storage-new/models/UserAuthenticationMethod.go b/storage-new/models/UserAuthenticationMethod.go
index 73a1552..bd185a2 100644
--- a/storage-new/models/UserAuthenticationMethod.go
+++ b/storage-new/models/UserAuthenticationMethod.go
@@ -2,6 +2,7 @@ package models
 
 import "database/sql/driver"
 
+// Authentication methods available
 type AuthenticationMethodType string
 
 const (
diff --git a/storage-new/models/UserBeingType.go b/storage-new/models/UserBeingType.go
index de699ba..e2a084a 100644
--- a/storage-new/models/UserBeingType.go
+++ b/storage-new/models/UserBeingType.go
@@ -4,6 +4,9 @@ import (
 	"database/sql/driver"
 )
 
+// The type of being an account identifies as
+// This is distinctly separate from the account being as being controlled by script
+// or other automated method
 type BeingType string
 
 const (
diff --git a/storage-new/models/UserBeings.go b/storage-new/models/UserBeings.go
index fbdb29b..2d749cf 100644
--- a/storage-new/models/UserBeings.go
+++ b/storage-new/models/UserBeings.go
@@ -1,6 +1,8 @@
 package models
 
-type UserBeings struct {
+// Defines an account to be a being of the set type
+// Multiple are possible for combination
+type UserToBeing struct {
 	User   User
 	UserId string
 	Being  BeingType `gorm:"type:being_type"`
diff --git a/storage-new/models/UserInfoField.go b/storage-new/models/UserInfoField.go
index 13e4507..15a5a1f 100644
--- a/storage-new/models/UserInfoField.go
+++ b/storage-new/models/UserInfoField.go
@@ -6,6 +6,10 @@ import (
 	"gorm.io/gorm"
 )
 
+// One key-value field attached to an account
+// If the value is an uri, the server may attempt to verify ownership
+// over that uri by checking the content for a `rel="me"` anchor
+// linking back to the account the field is attached to
 type UserInfoField struct {
 	gorm.Model       // Can actually just embed this as is here as those are not something directly exposed :3
 	Name             string
diff --git a/storage-new/models/UserRelation.go b/storage-new/models/UserRelation.go
deleted file mode 100644
index 50da947..0000000
--- a/storage-new/models/UserRelation.go
+++ /dev/null
@@ -1,9 +0,0 @@
-package models
-
-type UserRelation struct {
-	User         User
-	UserId       string
-	TargetUser   User
-	TargetUserId string
-	Relation     RelationType `gorm:"type:relation_type"`
-}
diff --git a/storage-new/models/UserRelationType.go b/storage-new/models/UserRelationType.go
index fef44fb..4d9b462 100644
--- a/storage-new/models/UserRelationType.go
+++ b/storage-new/models/UserRelationType.go
@@ -2,6 +2,7 @@ package models
 
 import "database/sql/driver"
 
+// How one account relates to another
 type RelationType string
 
 const (
diff --git a/storage-new/models/UserRemote.go b/storage-new/models/UserRemote.go
index 90c0ec7..6112a3a 100644
--- a/storage-new/models/UserRemote.go
+++ b/storage-new/models/UserRemote.go
@@ -2,6 +2,7 @@ package models
 
 import "gorm.io/gorm"
 
+// "Cached" extra data for accounts, in case they are remote
 type UserRemoteLinks struct {
 	// ---- Section: gorm
 	// Sets this struct up as a value that an Account may have
diff --git a/storage-new/models/UserRoles.go b/storage-new/models/UserRoles.go
deleted file mode 100644
index 97b52be..0000000
--- a/storage-new/models/UserRoles.go
+++ /dev/null
@@ -1,8 +0,0 @@
-package models
-
-type UserRole struct {
-	User   User
-	UserId string
-	Role   Role
-	RoleId uint
-}
diff --git a/storage-new/models/UserTags.go b/storage-new/models/UserTags.go
index 65fbccd..92254eb 100644
--- a/storage-new/models/UserTags.go
+++ b/storage-new/models/UserTags.go
@@ -1,6 +1,8 @@
 package models
 
-type UserTag struct {
+// A (hash)tag appearing on an account's profile description
+// Accounts may have multiple tags, but each tag may only be stored once at most
+type UserToTag struct {
 	User   User
 	UserId string
 	Tag    string
diff --git a/storage-new/models/UserToRole.go b/storage-new/models/UserToRole.go
new file mode 100644
index 0000000..657285f
--- /dev/null
+++ b/storage-new/models/UserToRole.go
@@ -0,0 +1,11 @@
+package models
+
+// A link of one account to one role
+// There may be multiple of these links per user and per role
+// But a role may only be linked at most once to the same user
+type UserToRole struct {
+	User   User
+	UserId string
+	Role   Role
+	RoleId uint
+}
diff --git a/storage-new/models/UserToUserRelation.go b/storage-new/models/UserToUserRelation.go
new file mode 100644
index 0000000..58c6b59
--- /dev/null
+++ b/storage-new/models/UserToUserRelation.go
@@ -0,0 +1,12 @@
+package models
+
+// A relation between two accounts
+// There may be multiple relations from an account X to an account Y,
+// each describing a different aspect
+type UserToUserRelation struct {
+	User         User
+	UserId       string
+	TargetUser   User
+	TargetUserId string
+	Relation     RelationType `gorm:"type:relation_type"`
+}