rogee
aeddedf2a3
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.
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# 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/`:
|
|
|
|
```bash
|
|
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/`):
|
|
|
|
```bash
|
|
# 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.
|