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 PostgreSQL, 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 \
  PG_ADDRESS="postgres://postgres@host.docker.internal/gochat" \
  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, Citus enablement) must be completed before running the container.

The container accepts PG_ADDRESS, CASSANDRA_ADDRESS, and MIGRATION_SCOPE=all|postgres|pg|cassandra|scylla.

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/       PostgreSQL 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