Files

T

rogee aeddedf2a3 Reorganize repo: backend/, deploy/, docs/ layout + AGENTS.md

Restructure the monorepo into clear top-level directories:
- backend/: Go module root (cmd, internal, pkg, configs, migrations,
  docs/swagger, scripts, tests, go.mod, Makefile, .air.toml)
- deploy/: Docker (Dockerfile, docker-compose*), quickstart, fluentd
- docs/: project documentation + reports/ (moved from repo root)
- AGENTS.md: new AI coding-agent guide at repo root

Update all references to the new layout:
- Dockerfile: COPY backend/go.mod, COPY backend/ (context = repo root)
- docker-compose files: context ../.., dockerfile deploy/docker/Dockerfile,
  env_file ../../.env, volume mounts ../../backend:/app
- deploy/quickstart/compose.yaml: dockerfile deploy/docker/Dockerfile
- CI: working-directory: backend for go commands, file deploy/docker/Dockerfile,
  coverage path backend/coverage.out, health_check backend/scripts/
- backend/Makefile: docker target uses -f ../deploy/docker/Dockerfile ../
- README: architecture tree, quickstart, config paths updated

Move root stray scripts (rename_models.*, run_m11_tests.sh, verify_build.sh,
gorm_bool_main.go) to backend/scripts/legacy/. All moves via git mv to
preserve history. Build, vet, SQLite tests, and docker compose config verified.

2026-07-07 14:44:12 +08:00

4.5 KiB

Raw Blame History

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
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.

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.

4.5 KiB Raw Blame History