dumpsterChat/GUILDED_ROADMAP.md

# dumpsterChat: Guilded Feature Parity Roadmap

**Goal:** Reach feature parity with Guilded (minus apps/PWA handled by existing PWA, monetization, screen share, PTT, streaming, friend requests, activity/game status).

**Base:** The app already has text chat, reactions, replies, mentions, voice channels, servers, channels, roles, permissions, invites, webhooks, bots, push notifications, and a terminal-aesthetic UI.

---

## Phase 1 — Core Chat Polish (2–3 weeks)

> Must-have features that every Guilded user expects. Low risk, high impact.

### 1.1 Direct Messages
- **Backend:** New `conversations` table (id, type: DM/group_dm, created_at), `conversation_members` join table. New `conversation_messages` table or reuse existing `messages` with a nullable `channel_id` and a required `conversation_id`.
- **Route:** `POST /conversations` (create DM), `GET /conversations`, `POST /conversations/{id}/messages`, `GET /conversations/{id}/messages`.
- **WS events:** `MESSAGE_CREATE` already works; just scope to conversation members.
- **Frontend:** New `ConversationsList` component in a sidebar panel (switch between servers view and DMs view). New `DMChatArea` or reuse `ChatArea` with a conversation context.
- **Estimated:** 4–6 files backend, 3–4 files frontend.

### 1.2 Full Markdown Rendering
- **Frontend:** Install `react-markdown` + `remark-gfm` (tables, strikethrough, task lists, autolinks). Replace the plain text renderer in `ChatArea` with `<ReactMarkdown>`.
- **Backend:** No changes (store raw markdown).
- **Estimated:** 1 file frontend.

### 1.3 Rich Embeds / Link Unfurling
- **Backend:** On message create, scan for URLs. For each URL, fetch `<title>`, `<description>`, `<og:image>` via `og:` meta tags. Store in `embeds` table (message_id FK, url, title, description, image_url, color).
- **Rate limit:** Max 5 embeds per message, async fetch with 2s timeout, cache for 24h.
- **Frontend:** Render embeds as cards below the message (dark card with image, title, description).
- **Estimated:** 2 files backend, 1 file frontend.

### 1.4 Message Search
- **Backend:** Add PostgreSQL full-text search. `ALTER TABLE messages ADD COLUMN search_vector tsvector`. Create a GIN index. Add trigger to populate on insert/update.
- **Route:** `GET /channels/{channelID}/messages/search?q=...&author_id=...&before=...&after=...&limit=25`.
- **Frontend:** Search bar in channel header or a dedicated search panel. Highlight matching terms in results.
- **Estimated:** 2 files backend, 2 files frontend.

### 1.5 Ban / Kick / Mute UI
- **Backend:** Already have `KICK_MEMBERS` and `BAN_MEMBERS` permissions. Add:
  - `DELETE /servers/{serverID}/members/{userID}` (kick)
  - `POST /servers/{serverID}/bans` (ban, with optional reason and delete_message_days)
  - `DELETE /servers/{serverID}/bans/{userID}` (unban)
  - `GET /servers/{serverID}/bans` (list bans)
  - `bans` table (server_id, user_id, reason, banned_by, created_at)
  - Mute: `server_mutes` table (server_id, user_id, muted_by, expires_at, reason). New permission `MUTE_MEMBERS`. Muted users cannot send messages or speak in voice.
- **Frontend:** Context menu on member list items (right-click or three-dot menu) with Kick/Ban/Mute options. Confirmation modals for each action.
- **Estimated:** 3 files backend, 2 files frontend.

### 1.6 Slowmode
- **Backend:** Add `slowmode_seconds` column to `channels`. New permission `MANAGE_SLOWMODE`. In message Create handler, check if user's last message in this channel was within `slowmode_seconds`; if so, return 429 with retry-after.
- **Frontend:** Show cooldown timer on the message input when slowmode is active. Channel settings to configure slowmode (0/5/10/30/60/120/300 seconds).
- **Estimated:** 2 files backend, 2 files frontend.

---

## Phase 2 — Moderation & Permissions (2–3 weeks)

> Unlocks serious server organization. Guilded's strength was granular permissions.

### 2.1 Per-Channel Permission Overrides
- **Backend:** New `channel_overrides` table (channel_id, target_type: role/user, target_id, allow_bitflags, deny_bitflags). Extend permission checker to layer channel overrides on top of role permissions.
- **Route:** `PUT /channels/{channelID}/permissions/{targetType}/{targetID}`, `GET /channels/{channelID}/permissions`, `DELETE /channels/{channelID}/permissions/{targetType}/{targetID}`.
- **Frontend:** Channel settings modal with a permissions tab. Matrix UI showing each permission with allow/deny/inherit toggles.
- **Estimated:** 3 files backend, 2 files frontend.

### 2.2 Expanded Permission Flags
- Add: `CREATE_INSTANT_INVITE`, `CHANGE_NICKNAME`, `MANAGE_NICKNAMES`, `MANAGE_ROLES`, `MANAGE_WEBHOOKS`, `EMBED_LINKS`, `ATTACH_FILES`, `ADD_REACTIONS`, `USE_EXTERNAL_EMOJIS`, `MENTION_EVERYONE`, `MUTE_MEMBERS`, `DEAFEN_MEMBERS`, `MOVE_MEMBERS`.
- Update permission checker to gate the corresponding handlers.
- **Estimated:** 2 files backend.

### 2.3 Role Colors & Hierarchy
- **Backend:** Add `color` (hex string) and `position` (integer) columns to `roles`. Permission resolution uses highest-position role's color.
- **Frontend:** Role editor with color picker. Member names shown in their highest role color in chat and member list.
- **Estimated:** 2 files backend, 2 files frontend.

### 2.4 Audit Log
- **Backend:** New `audit_log` table (server_id, user_id, action_type, target_type, target_id, reason, changes JSONB, created_at). Instrument all moderation actions (kick, ban, mute, role changes, channel CRUD, server settings changes) to write audit entries.
- **Route:** `GET /servers/{serverID}/audit-log?limit=50&before=...&action_type=...`.
- **Frontend:** Audit log panel in server settings. Shows who did what, when, with details. Filter by action type.
- **Estimated:** 3 files backend, 2 files frontend.

### 2.5 Bulk Message Delete
- **Backend:** `POST /channels/{channelID}/messages/bulk-delete` with `{ "messages": ["id1", "id2", ...] }`. Max 100 messages, must be within 14 days. Requires `MANAGE_MESSAGES`.
- **Frontend:** Select multiple messages (shift-click or checkbox mode), then bulk delete option.
- **Estimated:** 1 file backend, 1 file frontend.

---

## Phase 3 — Threads & Forums (2–3 weeks)

> Guilded's thread and forum system kept busy servers organized.

### 3.1 Threads
- **Backend:** Add `thread` channel type. New `threads` table (id, parent_channel_id, creator_id, name, archived_at, auto_archive_duration, message_count, last_message_at). Threads live under a parent channel. Messages in a thread are scoped to that thread.
- **Route:** `POST /channels/{channelID}/threads` (create thread from message or standalone), `PATCH /threads/{threadID}` (archive/unarchive), `GET /channels/{channelID}/threads` (list active threads).
- **WS events:** `THREAD_CREATE`, `THREAD_UPDATE`, `THREAD_DELETE`.
- **Frontend:** Thread panel that slides in from the right when clicking a thread. Thread starter message shown at top. Thread list in channel header area.
- **Estimated:** 3 files backend, 3 files frontend.

### 3.2 Forum Channels
- **Backend:** Add `forum` channel type. Forums display threads as a list of posts (title, tags, reply count, last activity). New `forum_tags` table (channel_id, name, emoji, color). Thread tags are assigned on creation.
- **Route:** CRUD for forum tags. Forum listing uses the threads endpoint with sorting (latest activity, most replies, creation date).
- **Frontend:** Forum channel renders as a post list (card layout) instead of a message stream. Each post card shows title, tags, reply count, last reply time, author avatar. Clicking opens the thread view.
- **Estimated:** 2 files backend, 3 files frontend.

---

## Phase 4 — User System Enhancements (1–2 weeks)

> Rich profiles and social features that make Guilded feel polished.

### 4.1 Rich User Profiles
- **Backend:** Extend `users` table with `banner_url`, `tagline` (max 128), `social_links` (JSONB array of {platform, url}), `pronouns` (max 40). Custom avatar upload (stored in MinIO, replace Gravatar dependency).
- **Route:** `GET /users/{userID}/profile` (public profile), `PATCH /auth/me` (update profile fields).
- **Frontend:** Clickable usernames open a profile modal/banner card. Shows avatar, display name, tagline, bio, social links, pronouns, badges, status, and shared servers.
- **Estimated:** 2 files backend, 2 files frontend.

### 4.2 Badges
- **Backend:** New `badges` table (id, name, icon, description). New `user_badges` join table (user_id, badge_id, granted_at, granted_by). Seed system badges (Server Booster, Early Adopter, Bot Developer, Verified, etc.).
- **Route:** `GET /users/{userID}/badges`, `POST /servers/{serverID}/badges` (create custom badge), `PUT /users/{userID}/badges/{badgeID}` (grant).
- **Frontend:** Badge display next to username in profiles and chat. Small icon grid.
- **Estimated:** 2 files backend, 1 file frontend.

### 4.3 Block List
- **Backend:** New `blocks` table (blocker_id, blocked_id, created_at). Blocked users: messages hidden, DMs blocked, presence hidden.
- **Route:** `POST /users/me/blocks`, `DELETE /users/me/blocks/{userID}`, `GET /users/me/blocks`.
- **Frontend:** Block option in user context menu. Blocked users section in settings.
- **Estimated:** 2 files backend, 1 file frontend.

---

## Phase 5 — Guilded Signature Features (3–4 weeks)

> The features that set Guilded apart: calendar, docs, lists, scheduling.

### 5.1 Calendar Channels
- **Backend:** New `calendar` channel type. New `events` table (channel_id, creator_id, title, description, start_time, end_time, recurrence_rule, location, color). New `event_rsvps` table (event_id, user_id, status: going/maybe/no, responded_at).
- **Route:** CRUD for events. `POST /events/{eventID}/rsvp` (RSVP). `GET /channels/{channelID}/events?from=...&to=...`.
- **WS events:** `EVENT_CREATE`, `EVENT_UPDATE`, `EVENT_DELETE`, `EVENT_RSVP`.
- **Frontend:** Calendar channel renders as a monthly/weekly/daily calendar view. Event cards show title, time, RSVP counts. Event detail modal with description, attendees, RSVP buttons. Auto-created voice channel for event start time (optional).
- **Estimated:** 3 files backend, 3 files frontend.

### 5.2 Docs Channels
- **Backend:** New `doc` channel type. New `documents` table (channel_id, creator_id, title, content TEXT, updated_at, locked_by). Docs are collaborative documents within a channel.
- **Route:** CRUD for documents. Lock/unlock for editing.
- **Frontend:** Docs channel renders as a wiki-style page list. Doc editor with markdown support. Version history (store diffs or snapshots).
- **Estimated:** 3 files backend, 2 files frontend.

### 5.3 Lists Channels (Task Management)
- **Backend:** New `list` channel type. New `list_items` table (channel_id, creator_id, title, description, assignee_id, due_date, status: todo/in_progress/done, position, completed_at). Supports nested items (parent_id).
- **Route:** CRUD for list items. Bulk status update. Filter by assignee/status.
- **Frontend:** Lists channel renders as a kanban board or checklist view. Drag-and-drop reordering. Assignee avatars, due date badges, status filters.
- **Estimated:** 3 files backend, 3 files frontend.

### 5.4 Scheduling / Availability
- **Backend:** New `availability` table (user_id, server_id, day_of_week, start_time, end_time). Users set their weekly availability.
- **Route:** `PUT /users/me/availability`, `GET /servers/{serverID}/availability` (aggregated view).
- **Frontend:** Availability grid in server settings or user profile. Shows when each member is generally available. Useful for scheduling events.
- **Estimated:** 2 files backend, 2 files frontend.

---

## Phase 6 — Voice Enhancements (1–2 weeks)

> Fill in the voice feature gaps (minus the excluded items).

### 6.1 Video Calls
- **LiveKit already supports video.** This is primarily a frontend feature.
- **Frontend:** Camera toggle button in VoicePanel. Video grid showing camera feeds of participants. Small overlay for self-view. LiveKit's `Room.createScreenTrack()` and camera track APIs.
- **Estimated:** 0 files backend, 2 files frontend.

### 6.2 Noise Suppression
- **Frontend:** Enable LiveKit's built-in noise suppression (RNNoise) via `room.options.audioCaptureDefaults.echoCancellation` and noise suppression settings. Alternatively, integrate DeepFilterNet3 WASM.
- **Estimated:** 0 files backend, 1 file frontend.

### 6.3 Voice Whisper
- **Backend:** Extend voice WS events to support targeted messages. `VOICE_WHISPER` event with target user IDs (not broadcast to whole room).
- **Frontend:** Whisper button in VoicePanel, select one or more users to whisper to. Audio routed only to selected users via LiveKit's track subscription API.
- **Estimated:** 1 file backend, 1 file frontend.

---

## Phase 7 — Notifications & UX Polish (1–2 weeks)

> Make the app feel complete and polished.

### 7.1 Per-Channel Notification Settings
- **Backend:** New `notification_settings` table (user_id, channel_id, level: all/mentions/none). Extend push dispatch to respect per-channel settings.
- **Route:** `PUT /channels/{channelID}/notifications`, `GET /users/me/notifications`.
- **Frontend:** Bell icon on channels with dropdown (All Messages, Mentions Only, Nothing). Notification settings in user preferences.
- **Estimated:** 2 files backend, 1 file frontend.

### 7.2 Email Notifications
- **Backend:** Queue-based email dispatch (using existing SMTP2GO relay config). `email_queue` table. Digest mode: aggregate unread messages and send hourly/daily digest.
- **Route:** `PUT /users/me/email-settings` (frequency: instant/hourly/daily/off).
- **Frontend:** Email notification preferences in settings.
- **Estimated:** 2 files backend, 1 file frontend.

### 7.3 Custom Emoji
- **Backend:** New `custom_emoji` table (server_id, name, image_url, uploaded_by). Emoji stored in MinIO. Max 50 per server.
- **Route:** CRUD for custom emoji. `GET /servers/{serverID}/emoji`.
- **Frontend:** Emoji picker extended with server emoji section. Custom emoji rendered inline in messages (`:emoji_name:` syntax).
- **Estimated:** 2 files backend, 2 files frontend.

### 7.4 Read Receipts
- **Backend:** New `read_states` table (user_id, channel_id, last_message_id, last_read_at). Updated on message fetch or when user views a channel.
- **Route:** `POST /channels/{channelID}/read` (mark as read). `GET /users/me/read-states`.
- **Frontend:** Unread dot/counter on channels. "New messages" divider in chat. Optional per-message read indicators (small avatar circles).
- **Estimated:** 2 files backend, 1 file frontend.

---

## Phase 8 — Server Groups & No-Code Bots (2 weeks)

> Guilded's organizational and automation features.

### 8.1 Server Groups (Sub-Servers)
- **Backend:** New `server_groups` table (server_id, name, icon, position). Channels can optionally belong to a group. Groups act as collapsible sections with their own header.
- **Route:** CRUD for server groups. Channel CRUD updated to accept optional `group_id`.
- **Frontend:** Server sidebar shows groups as collapsible sections containing channels. Drag channels between groups.
- **Estimated:** 2 files backend, 2 files frontend.

### 8.2 No-Code Bot Builder (Flow Bots)
- **Backend:** New `automations` table (server_id, trigger_type, trigger_config JSONB, actions JSONB, enabled, created_by). Trigger types: message_contains, user_join, reaction_added, scheduled. Actions: send_message, add_role, remove_role, send_webhook.
- **Route:** CRUD for automations. `POST /automations/{id}/test` (dry run).
- **Frontend:** Visual automation builder with trigger selector and action list. Simple if-then logic. Test button to verify.
- **Estimated:** 3 files backend, 3 files frontend.

---

## Summary: Dependency Order & Total Effort

| Phase | Focus | Weeks | Depends On |
|-------|-------|-------|------------|
| 1 | Core Chat Polish | 2–3 | — |
| 2 | Moderation & Permissions | 2–3 | Phase 1 (for mute context menu) |
| 3 | Threads & Forums | 2–3 | Phase 1 (markdown, embeds) |
| 4 | User System | 1–2 | — |
| 5 | Guilded Signature Features | 3–4 | Phase 1 (markdown for docs) |
| 6 | Voice Enhancements | 1–2 | — |
| 7 | Notifications & Polish | 1–2 | Phase 1 (search, threads) |
| 8 | Server Groups & Automation | 2 | Phase 2 (permissions) |

**Total estimated effort: 14–21 weeks** (one developer, full-time).

**Parallelizable:** Phases 1, 4, and 6 can run in parallel. Phases 2 and 3 can run in parallel after Phase 1. Phase 5 can start after Phase 1. Phase 7 and 8 can start after Phase 2.

**Critical path:** Phase 1 → Phase 3 (threads need markdown) → Phase 5 (docs need threads/markdown).

**Phases 1 + 4 + 6 in parallel** would cover ~60% of the gap and take 3–4 weeks.