Merge pull request #29 from aureateAnatidae/SQL-diagram

aureateAnatidae · web-flow · commit 376ed80d30ce · 2025-12-25T17:00:29.000-07:00
docs: Add season table design to database design documents
diff --git a/apps/backend/src/v1/match/router.ts b/apps/backend/src/v1/match/router.ts
@@ -15,7 +15,7 @@ app.get(
                 description: "Successful response",
                 content: {
                     "application/json": {
-                        schema: resolver(z.object({ sets: z.array(MatchReport) })),
+                        schema: resolver(z.object({ matches: z.array(MatchReport) })),
                     },
                 },
             },
@@ -39,7 +39,7 @@ app.post(
                 description: "Successful response",
                 content: {
                     "application/json": {
-                        schema: resolver(z.object({ set_id: z.int() })),
+                        schema: resolver(z.object({ match_id: z.int() })),
                     },
                 },
             },
diff --git a/apps/docsite/docs/Internal/concepts.md b/apps/docsite/docs/Internal/concepts.md
@@ -4,5 +4,12 @@ title: Concepts and Vocabulary
 
 # Disambiguation
 
-## Match/Set
-When we refer to the games played between players, which are reported to Grindcord, we use the term "match" over "set". Despite "set" being more common to refer to a past game, it shadows the term "set", which is a reserved word in programming (the data structure).
+## Use the word `Match` over `Set` to refer to recorded games
+When we refer to the games played between players, which are reported to Grindcord, we use the term "match" over "set". 
+
+Despite "set" being more common to refer to a past game, it already has a meaning in programming (the data structure) and may cause confusion. Using the word `Set` or `set` in code may also shadow the built-in `Set()` object in code.
+
+## GuildMember/User
+Grindcord is built for communities on Discord. Every user of Grindcord must also be a member of a guild (a Discord server) which has Grindcord installed.
+
+A user of Grindcord is uniquely identied by their `id` (that we disambiguate as `user_id`), and their participation in a guild with a `guild_id`. So, a [`GuildMember`](https://discord.com/developers/docs/resources/guild#guild-member-object) is an object from the Discord API which represents a [`user`](https://discord.com/developers/docs/resources/user#user-object) and their participation in that guild.
diff --git a/apps/docsite/docs/Internal/database.md b/apps/docsite/docs/Internal/database.md
@@ -13,19 +13,20 @@ Matches are reported to the backend. These reports contain the data:
 - Match count (3-0)
 - The fighters used by each respective user
 
-##### External Dependencies
+# External Dependencies
 
-A user of Grindcord SHOULD NOT be stored explicitly in our database. A [`GuildMember`](https://discord.com/developers/docs/resources/guild#get-guild-member) is an external dependency provided by Discord. A [`GuildMember`](https://discord.com/developers/docs/resources/guild#get-guild-member)'s `user_id` on the [`user`](https://discord.com/developers/docs/resources/user#user-object) field SHOULD be considered a primary key for our purposes.
+A user of Grindcord SHOULD NOT be stored explicitly in our database. A [`GuildMember`](https://discord.com/developers/docs/resources/guild#guild-member-object) is an external dependency provided by Discord. A [`GuildMember`](https://discord.com/developers/docs/resources/guild#guild-member-object)'s `user_id` on the [`user`](https://discord.com/developers/docs/resources/user#user-object) field SHOULD be considered a primary key for our purposes.
 
-A guild SHOULD NOT be stored explicitly in our database. A [`Guild`](https://discord.com/developers/docs/resources/guild#get-guild) is an external dependency provided by Discord. A `Guild`'s `guild_id` SHOULD be considered a primary key for our purposes.
+A guild SHOULD NOT be stored explicitly in our database. A [`Guild`](https://discord.com/developers/docs/resources/guild#guild-object) is an external dependency provided by Discord. A `Guild`'s `guild_id` SHOULD be considered a primary key for our purposes.
 
 ```mermaid
 erDiagram
-    direction LR
     Guild
     GuildMember
 ```
 
+# Matches Played by Users
+
 We split this into three tables.
 
 ```mermaid
@@ -52,30 +53,62 @@ erDiagram
 
 ##### Entity Relation Diagram for Matches, storing the data that would be reported by a user.
 
-The winner of the match can be inferred by selecting the `MatchPlayer` record with the highest `win_count` among records with the same `match_id`.
+The winner of the match SHALL be inferred by selecting the `MatchPlayer` record with the highest `win_count` among records with the same `match_id`.
 
 Note that `guild_id` is not stored by the `Match` table. When a match is reported for a particular `guild_id` (a unique ID assigned by Discord for a particular Discord server), the match is reported for that "guild's" current season (see below).
 
+# Seasons for Guilds
+
 ```mermaid
 erDiagram
     direction LR
     Match {
-        int         match_id
-        int         season_id
+        int         match_id    PK
+        int         season_id   FK
         datetime    created_at
     }
     Season {
-        int         season_id
+        int         season_id   PK
         string      guild_id
         datetime    start_at
         datetime    end_at
     }
     Match }|--|| Season: "was played during"
-    Guild ||--o{ Season: "has a current or past"
+    Guild ||--o{ Season: "has a"
 ```
 
 ##### Entity Relation Diagram for Seasons.
 
 A guild's "current" season is a `Season` record for which the `guild_id` matches, and the system datetime is between `start_at` and `end_at`.
 
-In addition, a `Season` in which participants will be designated an individual tier. Participants in a `Season` are `GuildMember` who report having participated in a `Match` during a `Season`.
+> Queries for a guild's current season should be optimized by creating an index on a guild.
+
+A `Match` is played in a `Season` if the `season_id` matches a `Season` record's `season_id`. 
+
+In addition, a `Season` in which participants will be designated an individual tier. Participants in a `Season` are `GuildMember`s who report having participated in a `Match` during a `Season`.
+
+# Tiers for Users Playing Matches
+
+> We recommand some in-memory key-value database to store tiers for current seasons. This is not implemented for the current release of Grindcord.
+
+For past seasons, Grindcord SHALL keep a record of each participating user's role.
+
+```mermaid
+erDiagram
+    direction LR
+    UserSeasonTier {
+        string      user_id     PK
+        int         season_id   PK,FK
+        string      tier_role_id
+    }
+    Season {
+        int         season_id   PK
+        string      guild_id    PK
+        datetime    start_at
+        datetime    end_at
+    }
+    UserSeasonTier ||..|| User: "assigns a tier to"
+    UserSeasonTier }|--|| Season: "determines tier in season"
+```
+
+A `tier_role_id` is the `role_id` of a role in a Discord server.
diff --git a/apps/docsite/docs/intro.md b/apps/docsite/docs/intro.md
@@ -7,7 +7,23 @@ sidebar_position: 1
 
 We have some user-friendly guides appropriate for all levels of expertise!
 
-# Reporting a set
-# Checking the leaderboard
-# Checking my sets
-# Checking other people's sets
+# For admins
+- Setting up Grindcord
+    - Installing Grindcord
+    - Permission and tier roles
+    
+# For users
+- Reporting a match
+- Checking the leaderboard
+- Checking my matches
+    - by date
+    - by win/loss
+    - by character
+- Checking other people's matches
+
+# Advanced: Self-hosting
+- Docker
+- Discord Bot
+- Bring your own database
+
+# Advanced: Exporting data
