gochat

Distributed real-time chat and voice backend written in Go.

REST API · WebSocket delivery · File uploads · Full-text search · Link-preview embeds · WebRTC voice and streaming

Changelog  ·  Go client  ·  TypeScript client  ·  License

Architecture

GoChat is service-oriented — each binary has a single focused responsibility. Services communicate through NATS for async events and share YugabyteDB YSQL, ScyllaDB, and KeyDB for state.

→ Full diagram, data-store reference, and voice flow walkthrough

Services

Features

• Account lifecycle with JWT-based authentication and email flows
• Guilds, channels, roles, permissions, invites, bans, and custom emoji
• Direct messages, threads, message history, mentions, and reactions
• File attachments, avatars, and icons via S3-compatible storage
• Link-preview embed generation from remote metadata
• Presence updates and real-time event fanout over WebSocket
• Full-text search indexing and query through OpenSearch
• Voice channels with region-aware SFU discovery, WebRTC relay, and separate screen/app streaming
• Structured observability — distributed traces, metrics, and logs via OTEL

Stack

Getting Started

Prerequisites

• Go 1.25.8 or newer
• Docker and Docker Compose
• GNU Make
• migrate CLI for creating migration files locally (make tools installs it)

Quick setup

make setup

Installs local tooling, starts the full Compose stack, initializes ScyllaDB, and applies all migrations.

Manual bootstrap

# Start infrastructure
docker compose up -d
docker compose exec scylla bash ./init-scylladb.sh

# Apply all migrations
make migrate

To test the migration image used in CI:

make build_migration_image
make migrate_image \
  YUGABYTE_ADDRESS="postgres://yugabyte:yugabyte@host.docker.internal:5433/gochat?sslmode=disable" \
  CASSANDRA_ADDRESS="cassandra://host.docker.internal/gochat?x-multi-statement=true"

CI publishes ghcr.io/<owner>/gochat-migrations:<tag> for releases and ghcr.io/<owner>/gochat-migrations:dev from the dev branch. Database bootstrap steps outside the migration files (ScyllaDB keyspace creation and YugabyteDB database creation) must be completed before running the container.

The container accepts YUGABYTE_ADDRESS, PG_ADDRESS as a backward-compatible YugabyteDB YSQL alias, CASSANDRA_ADDRESS, and MIGRATION_SCOPE=all|yugabyte|yb|ysql|cassandra|scylla.

For local Compose development, make migrate runs the official migrate/migrate container on the Compose network and mounts ./migration read-only. This uses service names like yugabyte:5433 and scylla, so host-port conflicts on 127.0.0.1:5433 do not affect development migrations. Override YUGABYTE_DB, YUGABYTE_USER, YUGABYTE_PASSWORD, or COMPOSE_PROJECT_NAME in .env when needed.

Local Compose creates the gochat YugabyteDB database with YUGABYTE_COLOCATION=false by default. This keeps core relational metadata sharded for high-load deployments; enable colocation only for small isolated test databases or tiny reference datasets.

Service configuration

Copy and edit the example config for each service:

api_config.example.yaml          ws_config.example.yaml
auth_config.example.yaml         sfu_config.example.yaml
stream_config.example.yaml       telemetry_gateway_config.example.yaml
attachments_config.example.yaml  indexer_config.example.yaml
webhook_config.example.yaml      embedder_config.example.yaml

Running Services

go run ./cmd/api
go run ./cmd/auth
go run ./cmd/ws
go run ./cmd/attachments
go run ./cmd/webhook
go run ./cmd/indexer
go run ./cmd/embedder
go run ./cmd/telemetrygateway
go run ./cmd/sfu          # voice media; runs separately from Compose
go run ./cmd/stream       # screen/app streaming media; runs separately from Compose

Useful Make targets:

Observability

The local stack uses OpenObserve and the OpenTelemetry Collector. Bootstrap dashboards with the Tools CLI:

go run ./cmd/tools observability bootstrap \
  --url http://localhost:5080 --org default \
  --user root@example.com --password Complexpass#123

go run ./cmd/tools observability smoke \
  --url http://localhost:5080 --org default \
  --user root@example.com --password Complexpass#123

Documentation

Repository Layout

cmd/             runnable services and operational tools
internal/        shared packages (transport, storage, search, mail, presence, server wiring)
migration/       YugabyteDB YSQL and ScyllaDB migrations
docs/            project documentation and generated OpenAPI schema
clients/api/     generated Go and TypeScript API clients
compose.yaml     local development stack
Makefile         bootstrap, migration, client generation, and rebuild targets