Real-time chat reference stack: Go WebSocket hub + SQLite history, React client, single-service Docker production image, CI with lint and coverage, Prometheus metrics, and portfolio-grade docs (scaling, threat model, ADRs).
- WebSocket broadcast with reconnect, buffered hub channel, bounded per-client outbound queues, and safe gorilla/websocket write serialization.
- Last 50 messages replayed on connect; SQLite timestamp parsing supports multiple on-disk formats.
GET /healthwith SQLite ping (503 when degraded);GET /metricsfor Prometheus.- Abuse controls: max username/message size (runes), per-IP WebSocket upgrade rate limit, per-client message rate limit, optional
Originallowlist. - Structured JSON logs (
slog), graceful shutdown, GitHub Actions (lint, test + coverage artifact, WebSocket load smoke, ESLint, build, production image smoke), Dependabot, Docker Compose, single-service production image. - Measured: zero message loss with p99 ≈ 6 ms broadcast delivery at 25 concurrent clients, and zero loss at 50 (Apple M1, Go 1.26); reproducible harness and honest O(N²) fan-out scaling notes in docs/LOAD_TESTING.md.
Frontend is intentionally a focused CRA SPA—see docs/FRONTEND.md for accessibility, performance notes, and how this repo positions backend/platform depth vs UI framework churn.
docker compose up --buildOpen http://localhost:3000 (UI) and http://localhost:8080/health (API health).
docker build -t chatster:prod .
docker run --rm -p 8080:8080 -v chatster-data:/data chatster:prodOpen http://localhost:8080. The Go backend serves the React build, API, metrics, and WebSocket from one origin.
Terminal 1 — API
cd backend && go run .Terminal 2 — React
cd frontend && npm install && npm startOpen http://localhost:3000. Use two browser tabs or windows to test live messaging.
| Variable | Scope | Purpose |
|---|---|---|
CHATSTER_HTTP_ADDR |
Backend | Listen address (default :8080). |
CHATSTER_DB_PATH |
Backend | SQLite file (default ./chatster.db). |
CHATSTER_STATIC_DIR |
Backend | Optional built frontend directory served by the Go backend. |
CHATSTER_ALLOWED_ORIGINS |
Backend | Comma-separated Origin values for WebSocket; empty = allow all (dev only). |
CHATSTER_WS_UPGRADE_RPS |
Backend | WS upgrades per IP per second (default 5; 0 disables). |
CHATSTER_WS_UPGRADE_BURST |
Backend | Token bucket burst for WS upgrades (default 10). |
CHATSTER_MESSAGE_RPS |
Backend | Chat messages per client per second (default 5; 0 disables). |
CHATSTER_MESSAGE_BURST |
Backend | Token bucket burst for per-client message sends (default 10). |
REACT_APP_WS_URL |
Frontend build | Full WebSocket URL (production / Docker build args). |
REACT_APP_WS_PORT |
Frontend dev | Backend port when using default dev WebSocket URL. |
See backend/.env.example and frontend/.env.example.
| Command | Description |
|---|---|
make test |
Backend tests + frontend tests (CI mode). |
make lint |
golangci-lint + ESLint (requires golangci-lint installed locally). |
make docker-up |
docker compose up --build. |
docker build -t chatster:prod . |
Build the single-service production image; CI also smokes this path. |
cd backend && go test -race ./... |
Go tests (includes HTTP + WebSocket integration tests). |
cd frontend && npm run test:ci |
Jest once. |
cd frontend && npm run build |
Optimized static build. |
- Architecture — components, data flow.
- Scaling & failure modes — what breaks first, what to do next.
- Threat model — security narrative and controls.
- Observability — metrics, logs, SLO sketch, tracing path.
- Load testing — reproducible WebSocket load harness.
- Deployment — single-container production image and host checklist.
- Frontend engineering — a11y, perf budget, positioning.
- Non-goals — explicit out-of-scope items.
- ADR index — architecture decisions.
- Workflows — CI, Dependabot, local and Docker dev.
- Operations — probes,
/metrics, checklist. - Contributing — PRs,
make lint, code of conduct.
Go 1.22 · Gorilla Mux & WebSocket · SQLite (CGO) · Prometheus · React 18 · Sass · Docker · GitHub Actions.
See LICENSE.