gochat/AGENTS.md

AGENTS.md — GoChat

Guidance for AI coding agents (and humans pairing with them) working in this repository.

Repository Layout

This is a monorepo with a clear separation between backend code, deployment artifacts, and documentation:

backend/      # Go backend (the Go module lives here)
  cmd/        # Entry points: gochat (server/seed), migrate, route_parity, ...
  internal/   # App logic: handler, service, repository, model, config, ws, ...
  pkg/        # Reusable packages: crypto, logger, pagination, response, ...
  configs/    # Viper config files (config.yaml + config.{env}.yaml)
  migrations/ # golang-migrate SQL files (sequential, .up.sql / .down.sql)
  docs/       # swaggo-generated Swagger Go package (imported by the router)
  scripts/    # migrate.sh, seed.sh, health_check.sh, route-parity tooling
  tests/      # e2e tests + test helpers
frontend/     # Chatwoot Vue 3 frontend (vendored for customization)
  app/javascript/   # Vue SPA source (dashboard, widget, sdk, portal, superadmin)
  app/views/        # ERB templates (vite-plugin-ruby entrypoint resolution)
  config/vite.json  # Vite-Rails bridge config
  enterprise/       # Enterprise edition frontend overlay
  package.json      # pnpm + Vite + Vue 3 toolchain
deploy/       # Deployment artifacts
  docker/     # Dockerfile, Dockerfile.dev, docker-compose.{yml,dev,prod,test}.yml
  quickstart/ # One-shot local/UAT Compose stack (PG+pgvector+Redis+Meilisearch+Mailhog)
  fluentd/    # Log shipping config
docs/         # Project documentation (architecture, requirements, plans, reports)

The Go module root is backend/ — run all go commands from there. Build context for Docker is the repository root (.), not backend/.

Build & Test Commands

All Go commands run from backend/:

cd backend

# Build
go build ./...                      # compile everything
make build                          # build ./cmd/gochat → bin/gochat

# Run
go run cmd/gochat/main.go serve     # API server (default subcommand)
go run cmd/gochat/main.go seed      # seed demo data

# Test
go test ./...                       # all tests
GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...  # no PG needed
go test -v -race ./...              # with race detector
go test -v ./tests/e2e/...          # e2e

# Lint
golangci-lint run ./...
go vet ./...

Docker (build context = repo root, Dockerfile in deploy/docker/):

# Quickstart stack from repo root
cd deploy/quickstart && cp .env.example .env && docker compose up -d --build

# Build image manually from backend/
make docker

Go Version & Tooling

• Go: 1.24+ (go.mod declares 1.24.0; CI uses 1.25). Toolchain: go1.24.4.
• HTTP: Gin v1.10
• ORM: GORM v2
• DB: PostgreSQL 16 + pgvector (SQLite supported for tests via GOCHAT_TEST_DB=sqlite)
• Config: Viper (multi-env overlay: config.yaml → config.{env}.yaml → .env)
• Swagger: swaggo/swag — generated docs live in backend/docs/ (a Go package imported by internal/router); do not move them out of the module.

Code Style & Conventions

• Tabs for Go/Makefile; 2-space for YAML/JSON/TOML (see .editorconfig).
• Match existing patterns in the surrounding code — do not reformat unrelated files.
• Layered architecture: handler → service → repository → model. Respect layer boundaries; don't call repositories directly from handlers.
• PG-only features (pgvector search, etc.) must guard with skipIfSQLite so SQLite test mode stays green.
• New DB schema changes go through numbered SQL migrations in backend/migrations/ (NNNNN_name.{up,down}.sql).

Configuration

• Config files: backend/configs/config.yaml (base) + config.dev.yaml / config.prod.yaml (env overlays).
• Viper search paths: ./configs, ./, /etc/gochat/.
• Runtime config dir is resolved from the base config's location, so env overlays load from the same dir automatically.
• Secrets/.env are gitignored — never commit them.

Deployment Notes

• The production Dockerfile (in deploy/docker/) uses repo root as build context and COPY backend/ for sources. When adding files the image needs, place them under backend/ or update the COPY directives.
• docker-compose*.yml files in deploy/docker/ use context: ../.. (repo root) and dockerfile: deploy/docker/Dockerfile.
• CI (.github/workflows/ci.yml) runs Go commands with working-directory: backend and builds the Docker image with file: ./deploy/docker/Dockerfile.

Frontend (Chatwoot Vue 3)

The frontend/ directory contains the Chatwoot frontend (v4.14.0) vendored for customization. It is a Vite + Vue 3 SPA that uses vite-plugin-ruby to integrate with Rails — the entrypoint resolution depends on Rails view templates and bin/vite is a Ruby binstub. To run the frontend you need Ruby + Bundler + pnpm.

cd frontend
bundle install              # installs vite_rails gem
pnpm install                # installs JS deps
overmind start -f Procfile.dev   # starts rails (3000) + vite (3036) + sidekiq

For parity smoke testing against the GoChat backend (no Rails needed for API smoke), see backend/scripts/parity_frontend_smoke.sh. The default CHATWOOT_DIR now points to ../frontend (repo root frontend/).

Things to Avoid

• Do not move backend/docs/*.go — they are a compiled Go package imported by the router.
• Do not add Go files to backend/scripts/legacy/ expecting them to be excluded — go build ./... compiles them; keep that directory for one-off scripts only.
• Do not commit .env, coverage.out, bin/, or tmp/.
• Do not rewrite git history or force-push without explicit instruction.