LobotomyLabs/dumpsterChat
2
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 1 Wiki Activity

Initial wiki: getting started, architecture, API, design, hosting, roadmap, troubleshooting

Dustin Newkirk
2026-06-26 14:53:00 -04:00
parent e83eb5f257
commit 4890caf4d3
9 changed files with 483 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API-Reference.md
+134
@@ -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`
Architecture.md
+66
@@ -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
Frontend-Design.md
+53
@@ -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] <dustin> hey everyone
[14:33] <friend> sup
```
## PWA
- `display: standalone`
- Theme color: `#282828`
- Background color: `#1d2021`
- Service worker caches static assets, network-first for API
Getting-Started.md
+42
@@ -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`.
Home.md
+13 -1
@@ -1 +1,13 @@
Welcome to the Wiki.
# 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)
Roadmap.md
+50
@@ -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
Self-Hosting.md
+73
@@ -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.
Troubleshooting.md
+42
@@ -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
_Sidebar.md
+10
@@ -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)