From 4890caf4d3139afb6bd4885666c858eebe7a09b2 Mon Sep 17 00:00:00 2001 From: hobokenchicken Date: Fri, 26 Jun 2026 14:53:00 -0400 Subject: [PATCH] Initial wiki: getting started, architecture, API, design, hosting, roadmap, troubleshooting --- API-Reference.md | 134 +++++++++++++++++++++++++++++++++++++++++++++ Architecture.md | 66 ++++++++++++++++++++++ Frontend-Design.md | 53 ++++++++++++++++++ Getting-Started.md | 42 ++++++++++++++ Home.md | 14 ++++- Roadmap.md | 50 +++++++++++++++++ Self-Hosting.md | 73 ++++++++++++++++++++++++ Troubleshooting.md | 42 ++++++++++++++ _Sidebar.md | 10 ++++ 9 files changed, 483 insertions(+), 1 deletion(-) create mode 100644 API-Reference.md create mode 100644 Architecture.md create mode 100644 Frontend-Design.md create mode 100644 Getting-Started.md create mode 100644 Roadmap.md create mode 100644 Self-Hosting.md create mode 100644 Troubleshooting.md create mode 100644 _Sidebar.md diff --git a/API-Reference.md b/API-Reference.md new file mode 100644 index 0000000..f017c76 --- /dev/null +++ b/API-Reference.md @@ -0,0 +1,134 @@ +# API Reference + +Base URL: `/api/v1` + +## Authentication + +All endpoints except auth require a valid session cookie (`dumpster_session`). + +### POST /auth/register + +```json +{ + "email": "user@example.com", + "username": "username", + "password": "hunter2" +} +``` + +Returns: `{ "id": "uuid" }` + +### POST /auth/login/password + +```json +{ + "email": "user@example.com", + "password": "hunter2" +} +``` + +Returns: `{ "id": "uuid" }` + +### POST /auth/logout + +Clears session cookie. Returns 204. + +## Servers + +### POST /servers + +Create a server. + +```json +{ + "name": "My Server", + "icon": "https://..." +} +``` + +### GET /servers + +List servers the authenticated user is a member of. + +### GET /servers/:id + +Get a specific server. + +### PATCH /servers/:id + +Update server name/icon. Owner only. + +### DELETE /servers/:id + +Delete a server. Owner only. + +## Channels + +### POST /channels + +```json +{ + "server_id": "uuid", + "name": "general", + "type": "text", + "category": "TEXT", + "position": 0 +} +``` + +### GET /channels?server_id=uuid + +List channels in a server. + +### GET /channels/:id + +Get a channel. + +### PATCH /channels/:id + +Update channel fields. + +### DELETE /channels/:id + +Delete a channel. + +## Messages + +### GET /messages/:channelID/messages?limit=50&before=messageID + +Get messages in a channel. Cursor-based pagination. + +### POST /messages/:channelID/messages + +```json +{ + "content": "hello" +} +``` + +### PATCH /messages/:messageID + +```json +{ + "content": "edited message" +} +``` + +### DELETE /messages/:messageID + +Delete a message. Author only. + +## WebSocket + +Connect to `/ws` with the session cookie. Incoming events: + +- `MESSAGE_CREATE` +- `MESSAGE_UPDATE` +- `MESSAGE_DELETE` +- `CHANNEL_CREATE` +- `CHANNEL_UPDATE` +- `CHANNEL_DELETE` +- `SERVER_MEMBER_ADD` +- `SERVER_MEMBER_REMOVE` +- `PRESENCE_UPDATE` +- `TYPING_START` diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 0000000..bf72196 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,66 @@ +# Architecture + +## Stack + +| Layer | Technology | +|-------|-----------| +| Backend language | Go | +| HTTP framework | chi/v5 | +| Database | PostgreSQL 16 | +| Cache / presence | Valkey 8 (Redis-compatible) | +| WebSocket gateway | gorilla/websocket | +| Voice / video | LiveKit (self-hosted) | +| TURN/STUN | coturn | +| File storage | minio | +| Reverse proxy | Caddy | +| Frontend | React 18 + TypeScript + Vite | +| Styling | Tailwind CSS 3.4 (Gruvbox dark terminal theme) | +| State management | Zustand | + +## Service layout + +``` + ┌──────────────────┐ + │ Clients │ + └────────┬─────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ┌─────┴──────┐ ┌──────┴──────┐ + │ Web App │ │ TUI Client │ + │ (PWA) │ │ (Phase 5) │ + │ React/TS │ │ bubbletea │ + └─────┬──────┘ └──────┬──────┘ + │ │ + └──────────────────┼──────────────────┘ + │ + ┌────────┴────────┐ + │ Caddy │ + │ (TLS, proxy) │ + └────────┬────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ +┌─────┴──────────┐ ┌───────┴──────────┐ +│ Go API Server │ │ LiveKit │ +│ REST + WS │ │ voice/video │ +│ │ │ + coturn │ +└─────────┬─────────┘ └──────────────┘ + │ + ┌────────┼───────────┐ + │ Postgres │ Valkey │ MinIO │ + └───────────────────┘ +``` + +## Backend structure + +- `cmd/server` - main API + WebSocket gateway +- `cmd/migrate` - database migration CLI +- `internal/auth` - password hashing, sessions, login/register +- `internal/db` - PostgreSQL connection and migrations +- `internal/gateway` - WebSocket hub, clients, events +- `internal/server` - server CRUD +- `internal/channel` - channel CRUD +- `internal/message` - message CRUD with pagination +- `internal/middleware` - session middleware, auth guard +- `internal/config` - environment config diff --git a/Frontend-Design.md b/Frontend-Design.md new file mode 100644 index 0000000..fe70219 --- /dev/null +++ b/Frontend-Design.md @@ -0,0 +1,53 @@ +# Frontend Design + +## Visual style: terminal aesthetic + +Dumpster looks like a terminal application. No rounded corners. No gradients. Monospace everywhere. + +## Color palette: Gruvbox dark + +| Token | Hex | Usage | +|-------|-----|-------| +| `--gb-bg-h` | `#1d2021` | Deepest background | +| `--gb-bg` | `#282828` | Main background | +| `--gb-bg-s` | `#3c3836` | Sidebar backgrounds | +| `--gb-bg-t` | `#504945` | Elevated surfaces | +| `--gb-fg` | `#ebdbb2` | Main text | +| `--gb-fg-s` | `#d5c4a1` | Secondary text | +| `--gb-fg-t` | `#bdae93` | Tertiary text | +| `--gb-orange` | `#fe8019` | Accent, active states | +| `--gb-green` | `#b8bb26` | Online indicator | +| `--gb-yellow` | `#fabd2f` | Idle/away | +| `--gb-red` | `#fb4934` | Errors, DND | +| `--gb-aqua` | `#8ec07c` | Mentions, notifications | + +## Typography + +- Primary font: JetBrains Mono +- Size: 14px base +- Usernames: bold, colored by role +- Timestamps: 12px, muted, bracketed `[HH:MM]` +- Category headers: 11px, UPPERCASE + +## Layout + +Desktop layout is 4 panes framed by box-drawing characters: + +1. **Server bar** (48px): server initials in brackets `[D]` +2. **Channel sidebar** (220px): categories + `#text` / `🔊 voice` channels +3. **Chat area** (flex): IRC-style messages + `> _` input +4. **Member list** (200px): status dots + usernames + +Messages render as: + +``` +[14:32] hey everyone +[14:33] sup +``` + +## PWA + +- `display: standalone` +- Theme color: `#282828` +- Background color: `#1d2021` +- Service worker caches static assets, network-first for API diff --git a/Getting-Started.md b/Getting-Started.md new file mode 100644 index 0000000..93b20d8 --- /dev/null +++ b/Getting-Started.md @@ -0,0 +1,42 @@ +# Getting Started + +## Prerequisites + +- Go 1.24+ +- Node.js 22+ +- Docker + Docker Compose +- A domain or local dev environment + +## Clone and build + +```bash +git clone ssh://git@git.dustin.coffee:2222/hobokenchicken/dumpsterChat.git +cd dumpsterChat +cp .env.example .env +``` + +Edit `.env` with your settings. Then start backing services: + +```bash +make docker-dev +``` + +Run migrations: + +```bash +go run ./cmd/migrate -direction=up +``` + +Start the server: + +```bash +make run +``` + +Start the web dev server: + +```bash +make dev-web +``` + +Visit `http://localhost:5173`. diff --git a/Home.md b/Home.md index 5d08b7b..3f980a9 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,13 @@ -Welcome to the Wiki. \ No newline at end of file +# Dumpster Wiki + +Welcome to the Dumpster wiki. This is the living documentation for the self-hosted Discord-like chat platform. + +## Quick links + +- [Getting Started](Getting-Started) +- [Architecture](Architecture) +- [API Reference](API-Reference) +- [Frontend Design](Frontend-Design) +- [Self-Hosting](Self-Hosting) +- [Development Roadmap](Roadmap) +- [Troubleshooting](Troubleshooting) diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..f551f2a --- /dev/null +++ b/Roadmap.md @@ -0,0 +1,50 @@ +# Development Roadmap + +## Phase 1: Core Chat (MVP) — DONE + +- [x] Go backend scaffold +- [x] PostgreSQL migrations +- [x] Auth (register, login, sessions, Argon2id) +- [x] WebSocket gateway +- [x] Server CRUD +- [x] Channel CRUD +- [x] Message CRUD with pagination +- [x] React frontend scaffold +- [x] Terminal-styled layout +- [x] Zustand stores (auth, server, channel, message, websocket) +- [x] Docker Compose dev stack + +## Phase 2: Voice & Video + +- [ ] LiveKit integration in frontend +- [ ] Voice channels (persistent, drop-in) +- [ ] Video calls +- [ ] Screen sharing +- [ ] Mute/deafen controls + +## Phase 3: Polish & PWA + +- [ ] PWA manifest and service worker +- [ ] Web Push notifications (VAPID) +- [ ] WebAuthn / passkeys +- [ ] Mobile-responsive layout +- [ ] Message reactions, replies, threads +- [ ] Typing indicators +- [ ] Online presence +- [ ] Meilisearch message search +- [ ] User profiles +- [ ] Invite links + +## Phase 4: Bots & Extensibility + +- [ ] Bot application creation +- [ ] Bot token authentication +- [ ] Bot WebSocket gateway +- [ ] Slash commands +- [ ] Incoming webhooks + +## Phase 5: TUI Client + +- [ ] Bubbletea terminal client +- [ ] IRC-style chat in terminal +- [ ] LiveKit Go SDK for audio-only voice diff --git a/Self-Hosting.md b/Self-Hosting.md new file mode 100644 index 0000000..751abd1 --- /dev/null +++ b/Self-Hosting.md @@ -0,0 +1,73 @@ +# Self-Hosting + +## Docker Compose (full stack) + +```bash +make docker-up +``` + +This starts: + +- `app` - Go backend + built web frontend +- `postgres` - PostgreSQL 16 +- `valkey` - Redis-compatible cache +- `minio` - S3-compatible file storage +- `livekit` - WebRTC SFU for voice/video +- `coturn` - TURN/STUN for NAT traversal +- `caddy` - Reverse proxy with auto-TLS (prod) or HTTP (dev) + +## Environment variables + +Copy `.env.example` to `.env` and set: + +```env +DUMPSTER_HOST=chat.your.domain +DUMPSTER_PORT=8080 +DUMPSTER_SECRET=change-me + +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 +POSTGRES_USER=dumpster +POSTGRES_PASSWORD=change-me + +VALKEY_URL=redis://valkey:6379 + +MINIO_ENDPOINT=minio:9000 +MINIO_ACCESS_KEY=dumpster +MINIO_SECRET_KEY=change-me +MINIO_BUCKET=dumpster-files + +LIVEKIT_API_KEY=devkey +LIVEKIT_API_SECRET=change-me + +VAPID_PUBLIC_KEY=... +VAPID_PRIVATE_KEY=... +VAPID_SUBJECT=mailto:admin@your.domain +``` + +## Ports required + +| Port | Service | +|------|---------| +| 80/443 | Caddy reverse proxy | +| 7880-7882 | LiveKit signaling and media | +| 3478/udp | coturn TURN | +| 5349 | coturn TURN TLS | +| 50000-50100/udp | LiveKit relay | +| 10000-20000/udp | coturn media relay | + +## Production TLS + +For production, update `docker/Caddyfile`: + +``` +chat.your.domain { + reverse_proxy /api/* app:8080 + reverse_proxy /ws app:8080 + reverse_proxy /livekit/* livekit:7880 + root * /srv/web + file_server +} +``` + +Remove `auto_https off` and Caddy will fetch Let's Encrypt certificates. diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..178f3ca --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,42 @@ +# Troubleshooting + +## Build failures + +### `tsc: command not found` + +Install TypeScript globally or run `npm install --include=dev` in `web/`. + +### Go module not found + +```bash +go mod tidy +go build ./... +``` + +## Database connection errors + +Ensure PostgreSQL is running and `.env` has correct credentials: + +```bash +docker compose -f docker/compose.yml logs postgres +``` + +## WebSocket not connecting + +Check Caddyfile includes the WebSocket upgrade headers: + +``` +handle /ws { + reverse_proxy app:8080 { + header_up Connection {>Connection} + header_up Upgrade {>Upgrade} + } +} +``` + +## Voice/video not working + +- Verify LiveKit and coturn containers are running +- Ensure UDP ports 7882, 3478, 50000-50100, and 10000-20000 are exposed +- Check browser console for WebRTC ICE failures +- Verify `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` match in both LiveKit and coturn diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..ebd0786 --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,10 @@ +# Navigation + +- [Home](Home) +- [Getting Started](Getting-Started) +- [Architecture](Architecture) +- [API Reference](API-Reference) +- [Frontend Design](Frontend-Design) +- [Self-Hosting](Self-Hosting) +- [Roadmap](Roadmap) +- [Troubleshooting](Troubleshooting)