rogee
321c61aaae
Copy the Chatwoot (v4.14.0) frontend runnable subset into frontend/ for customization: - app/javascript/ (Vue SPA: dashboard, widget, sdk, portal, superadmin) - app/views/ (ERB templates for vite-plugin-ruby entrypoint resolution) - app/helpers/, app/assets/ (Rails view helpers, static assets) - enterprise/ (Enterprise edition frontend overlay) - config/vite.json, vite.config.ts, bin/vite (Vite-Rails toolchain) - package.json, pnpm-lock.yaml, tailwind/postcss/eslint configs - Gemfile, Gemfile.lock (vite_rails gem for bin/vite binstub) Excluded Rails backend: controllers, models, services, jobs, mailers, policies, db, lib, spec, public, node_modules. Update references to the new frontend location: - .gitignore: exclude frontend build artifacts (node_modules, tmp, packs), keep frontend/bin/ and frontend/vendor/ via negation - backend/scripts/parity_frontend_smoke.sh: CHATWOOT_DIR default reference/chatwoot -> ../frontend - backend/scripts/parity_frontend_browser_smoke.mjs: same default update - AGENTS.md: add frontend section with Rails/Vite coupling notes - README: architecture tree includes frontend/
126 lines
5.6 KiB
Markdown
126 lines
5.6 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
|
|
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/`:
|
|
|
|
```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`.
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
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.
|