Draft: move to Prisma ORM

.github/workflows/build.yml

@@ -13,12 +13,12 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [25.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v6
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'yarn'

.gitignore

@@ -64,3 +64,5 @@ typings/
 .idea/
 
 build/
+
+/generated/prisma

.vscode/settings.json

@@ -6,11 +6,19 @@
     "javascript.preferences.importModuleSpecifier": "relative",
     "typescript.preferences.importModuleSpecifier": "relative",
     "files.exclude": {
-        "node_modules": true
+        "**/.git": true,
+        "**/.svn": true,
+        "**/.hg": true,
+        "**/CVS": true,
+        "**/.DS_Store": true,
+        "**/Thumbs.db": true,
+        "node_modules": true,
+        "**/.idea": true
     },
     "npm.packageManager": "yarn",
     "files.eol": "\n",
     "editor.insertSpaces": true,
     "editor.tabSize": 4,
-    "typescript.enablePromptUseWorkspaceTsdk": true
+    "typescript.enablePromptUseWorkspaceTsdk": true,
+    "explorerExclude.backup": {}
 }

biome.json

@@ -1,6 +1,12 @@
 {
-    "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
-    "assist": { "actions": { "source": { "organizeImports": "on" } } },
+    "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+    "assist": {
+        "actions": {
+            "source": {
+                "organizeImports": "on"
+            }
+        }
+    },
     "vcs": {
         "enabled": true,
         "clientKind": "git",

docs/README.md

@@ -0,0 +1,25 @@
+# DataDrop Documentation
+
+This folder is the project knowledge base for Issue 93 and related implementation work.
+
+## What is in here
+
+- [Issue 93 Specification](specs/issue-93-specification.md)
+- [Architecture](specs/architecture.md)
+- [Membership State Machine](specs/state-machine.md)
+- [BPMN-Style Lifecycle](specs/bpmn-lifecycle.md)
+- [MVP Scope](specs/mvp-scope.md)
+- [Discord API and Discord.js Sources](specs/discord-sources.md)
+- [GitHub Sources](specs/github-sources.md)
+- [Strict Traceability Matrix](specs/traceability-matrix.md)
+- [Roadmap Beyond MVP](specs/non-mvp-roadmap.md)
+
+## Visual Assets
+
+- Feature list snapshot: ![Issue 93 Feature Map](assets/issue-93-feature-list.svg)
+- Project visual marker: ![DataDrop Visual Marker](assets/datadrop-visual-marker.svg)
+
+## Notes
+
+- Mermaid diagrams are embedded directly in markdown files.
+- Any statement tied to Discord API or Discord.js behavior is sourced in [Discord API and Discord.js Sources](specs/discord-sources.md).

docs/specs/architecture.md

@@ -0,0 +1,68 @@
+# Architecture
+
+## Context
+
+DataDrop has two behavior entrypoints:
+
+1. Discord Bot runtime
+2. Web App + Backend API
+
+Both must enforce the same business rules and write to the same domain model.
+
+## High-Level System Diagram
+
+```mermaid
+flowchart LR
+    U[User] -->|Discord Client| D[Discord Platform]
+    U -->|Browser| W[Web App]
+
+    D -->|Gateway Events| B[DataDrop Bot]
+    B -->|Commands, role updates, onboarding checks| D
+
+    W -->|JWT-authenticated calls| A[DataDrop Backend API]
+    A --> DB[(PostgreSQL)]
+    B --> DB
+
+    DB --> Q[Dead Letter Queue]
+    Q --> R[Staff Remediation Panel]
+
+    A --> O[Audit and Security Logs]
+    B --> O
+```
+
+## Tenant and Access Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Web as Web App
+    participant Discord as Discord OAuth API
+    participant API as Backend API
+    participant DB as PostgreSQL
+
+    User->>Web: Login with Discord
+    Web->>Discord: OAuth exchange
+    Discord-->>Web: user identity + guild list
+    Web->>API: fetch guilds known by DataDrop for user
+    API->>DB: read guild memberships and roles
+    DB-->>API: guilds from platform scope
+    API-->>Web: intersection list for guild selector
+    User->>Web: select guild
+    Web->>API: request guild context
+    API->>DB: action-time authorization check
+    DB-->>API: allowed or denied
+    API-->>Web: scoped response
+```
+
+## Cross-Entrypoint Consistency
+
+Design rule:
+
+- Bot and API writes use strict optimistic locking
+- Transition preconditions include expected state and expected version
+- Conflict retries are bounded
+- Retry exhaustion creates dead-letter records
+
+## Source Notes
+
+For Discord gateway and member update semantics, see [Discord API and Discord.js Sources](discord-sources.md).

docs/specs/bpmn-lifecycle.md

@@ -0,0 +1,47 @@
+# BPMN-Style Lifecycle Flow
+
+This document captures the intended operational flow for onboarding, eligibility, rules acceptance, verification, and admin override handling.
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Member joins guild] --> B[Discord onboarding starts]
+    B --> C{Onboarding completed?}
+    C -->|No| B
+    C -->|Yes| D[Eligibility evaluation from roles and rules]
+
+    D --> E{Eligible?}
+    E -->|No| X[RejectedNotEligible]
+    E -->|Yes| F[RulesAccepted]
+
+    F --> G[VerificationPending]
+    G --> H{Verification success?}
+    H -->|Code verified| I[Verified]
+    H -->|Admin implicit verification valid| I
+    H -->|Deadline exceeded| J[Kicked or Rejected]
+
+    G --> K{Admin implicit verification request}
+    K -->|State != VerificationPending| L[Hard reject override]
+    K -->|Email missing| M[Hard fail override]
+    K -->|State ok and email present| I
+
+    I --> N{Reverification campaign targeted?}
+    N -->|No| O[Remain Verified]
+    N -->|Yes| P[Return to VerificationPending]
+```
+
+## Rule Highlights
+
+1. Rules acceptance remains per guild because onboarding is a guild-bound Discord flow.
+2. Global verification identity does not bypass guild onboarding acceptance.
+3. Manual implicit verification is constrained to `VerificationPending` and requires email presence.
+4. Historical override does not provide permanent bypass entitlement in future campaigns.
+
+## Discord-Specific Notes
+
+1. Member updates are observed through gateway member update events.
+2. Onboarding and member flags are platform-defined by Discord.
+3. Membership screening and pending semantics are Discord-defined.
+
+Reference all platform-specific semantics through [Discord API and Discord.js Sources](discord-sources.md).

docs/specs/discord-sources.md

@@ -0,0 +1,49 @@
+# Discord API and Discord.js Sources
+
+This file lists the authoritative references used for Discord-specific behavior statements in the documentation.
+
+## Discord API Sources
+
+1. Gateway Events overview
+   - https://docs.discord.com/developers/events/gateway-events
+
+2. Guild Member Update event
+   - https://docs.discord.com/developers/events/gateway-events#guild-member-update
+
+3. Guild Resource and Guild Member object
+   - https://docs.discord.com/developers/resources/guild
+
+4. Guild Member flags including onboarding-related flags
+   - https://docs.discord.com/developers/resources/guild#guild-member-object-guild-member-flags
+
+5. Membership screening `pending` behavior
+   - https://docs.discord.com/developers/resources/guild#membership-screening-object
+
+6. Guild onboarding object and prompts
+   - https://docs.discord.com/developers/resources/guild#guild-onboarding-object
+
+7. Message timestamp formatting in Discord messages
+   - https://docs.discord.com/developers/reference#message-formatting
+
+## Discord.js Sources
+
+1. Discord.js guide and docs entrypoint
+   - https://discord.js.org
+
+2. Events reference including guild member updates
+   - https://discord.js.org/docs/packages/discord.js/main/Events:Enum
+
+3. `GuildMember` structure and role/member fields
+   - https://discord.js.org/docs/packages/discord.js/main/GuildMember:Class
+
+## How to Use These Sources in This Project
+
+1. If a behavior claim depends on Discord platform event semantics, cite a Discord API source above.
+2. If a behavior claim depends on discord.js runtime object shape or event names in code, cite a Discord.js source above.
+3. For ambiguous platform behavior, rely on observed runtime tests in development and document the result in project docs.
+
+## Project-Level GitHub Sources
+
+Repository and issue references are maintained in:
+
+- [GitHub Sources](github-sources.md)