English | 简体中文
A teaching-oriented real-time chat application that demonstrates how to build and reason about a modern full-stack system with Go, React, PostgreSQL, WebSocket, tests, observability, and OpenSpec-driven change management.
This project is designed to be:
- Runnable: you can start the stack locally in minutes
- Understandable: the backend, frontend, docs, and specs are kept explicit
- Teachable: the repository is organized so learners can follow how a real-time product fits together
If you want a compact codebase that still covers authentication, rooms, messages, WebSocket delivery, monitoring, and deployment basics, this repo is for you.
- JWT login, refresh tokens, and request authentication
- Room-based WebSocket messaging and message persistence
- Go service layering and database-backed handlers
- React + TypeScript client structure for chat flows
- Prometheus metrics, health checks, and release workflows
- How OpenSpec can keep product and engineering changes aligned
- Go 1.24
- Node.js 22
- Docker
git clone https://github.com/LessUp/chatroom.git
cd chatroom
docker compose up -d postgres
# backend
go run ./cmd/server
# frontend (another terminal)
npm --prefix frontend ci
npm --prefix frontend run dev| Surface | URL |
|---|---|
| Frontend dev server | http://localhost:5173 |
| Backend | http://localhost:8080 |
| Docs site | https://lessup.github.io/chatroom/ |
- Docs site: English · 中文
- Getting started: EN · ZH
- Architecture walkthrough: EN · ZH
- API reference: EN · ZH
- OpenSpec source of truth:
openspec/specs/
| Layer | Technology |
|---|---|
| Backend | Go 1.24, Gin, GORM, Gorilla WebSocket, zerolog |
| Frontend | React 19, TypeScript, Vite 7, Tailwind CSS v4 |
| Database | PostgreSQL 16 |
| Observability | Prometheus, Grafana |
| Delivery | Docker, GitHub Actions, GitHub Pages |
chatroom/
├── cmd/server/ # application entrypoint
├── internal/ # backend application code
├── frontend/ # React client
├── docs/ # documentation site
├── openspec/ # specs and active changes
└── deploy/ # Docker and Kubernetes assets
Non-trivial repository changes are managed through OpenSpec:
/opsx:explore
/opsx:propose <change-name>
/opsx:apply <change-name>
/opsx:archive <change-name>The canonical requirements live in openspec/specs/, and active work lives in openspec/changes/.
docker compose up -d postgres
make lint
go test -race ./...
npm --prefix frontend run test
npm --prefix frontend run build
npm --prefix docs ci
npm --prefix docs run docs:build- Contribution guide: CONTRIBUTING.md
- Security policy: SECURITY.md
- Release history: CHANGELOG.md