Development Guide
This document explains how to set up your development environment, run tests, and contribute to the project.
Requirements
| Tool | Version | Purpose |
|---|---|---|
| Go | 1.24+ | Backend development |
| Node.js | 20+ | Frontend development, docs build |
| Docker | Latest | PostgreSQL database |
| Make | Any | Build commands |
Quick Start
1. Start Database
bash
# Start PostgreSQL using Docker
docker compose up -d postgres
# Or manually
docker run -d --name chatroom-db \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=chatroom \
-p 5432:5432 \
postgres:16-alpine1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
2. Configure Environment
bash
# Copy environment template
cp .env.example .env
# Edit configuration (defaults work for development)
# Note: The app doesn't auto-load .env files
export $(cat .env | xargs)1
2
3
4
5
6
2
3
4
5
6
3. Start Backend
bash
# Download dependencies and run
go mod download
go run ./cmd/server
# Or use Make
make run1
2
3
4
5
6
2
3
4
5
6
4. Start Frontend
bash
cd frontend
npm install
npm run dev1
2
3
2
3
The frontend dev server automatically proxies /api and /ws to the backend at localhost:8080.
Common Commands
Backend
bash
go mod tidy # Tidy dependencies
go build ./... # Build all packages
go test -race ./... # Run tests with race detection
go test -cover ./... # Run tests with coverage1
2
3
4
2
3
4
Frontend
bash
cd frontend
npm run lint # Lint check
npm run test # Run tests
npm run build # Production build1
2
3
4
2
3
4
Documentation
bash
cd docs
npm install
npm run docs:dev # Local preview
npm run docs:build # Build docs site1
2
3
4
2
3
4
Project Structure
chatroom/
├── cmd/server/ # Application entrypoint
├── internal/ # Private application code
│ ├── auth/ # JWT authentication
│ ├── config/ # Configuration management
│ ├── db/ # Database connection
│ ├── models/ # Data models
│ ├── mw/ # HTTP middleware
│ ├── sanitize/ # Input sanitization
│ ├── server/ # HTTP handlers
│ ├── service/ # Business logic
│ └── ws/ # WebSocket implementation
├── frontend/ # React frontend
│ └── src/
│ ├── components/ # UI components
│ ├── hooks/ # Custom hooks
│ ├── screens/ # Page components
│ └── test/ # Test utilities
├── docs/ # VitePress documentation
├── openspec/ # OpenSpec specifications
└── deploy/ # Deployment configs1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
OpenSpec Workflow
This project uses OpenSpec-driven development:
- Explore:
/opsx:explore- Deep dive into requirements - Propose:
/opsx:propose <name>- Create change proposal - Implement:
/opsx:apply <name>- Execute tasks - Archive:
/opsx:archive <name>- Complete and archive
See openspec/specs/ for detailed specifications.
Code Standards
Go
- Use
golangci-lintfor linting - Follow Go official style
- Test critical business logic
TypeScript
- Use ESLint + Prettier
- Strict TypeScript mode
- Functional components with Hooks
Commits
Use Conventional Commits:
feat: add new feature
fix: fix bug
docs: documentation update
refactor: code refactoring
test: test related
chore: build/tool changes1
2
3
4
5
6
2
3
4
5
6
Environment Variables
| Variable | Default | Description |
|---|---|---|
APP_PORT | 8080 | HTTP port |
APP_ENV | dev | Environment |
DATABASE_DSN | - | PostgreSQL connection string |
JWT_SECRET | dev-secret-change-me | JWT secret (must change in production) |
ALLOWED_ORIGINS | - | CORS whitelist |
WS_MAX_MESSAGE_SIZE | 1048576 | Max WebSocket message bytes |
WS_MAX_CONTENT_SIZE | 2000 | Max chat message characters |
DB_MAX_IDLE_CONNS | 5 | DB pool idle connections |
DB_MAX_OPEN_CONNS | 20 | DB pool max connections |
Troubleshooting
Database Connection Failed
Ensure PostgreSQL is running:
bash
docker compose up -d postgres
docker compose ps1
2
2
Frontend Can't Connect to Backend
Check if backend is running on port 8080. Vite dev server auto-proxies requests.
Tests Failing
Tests require PostgreSQL:
bash
docker compose up -d postgres
go test ./...1
2
2