AGENTS.md — backend

Module & Layout

Go module: github.com/XingfenD/yoresee_doc (rooted at backend/).

cmd/main.go                  — API server entry (Connect RPC)
cmd/migrate/                 — GORM AutoMigrate (runs first on startup)
cmd/db_init/                 — seed data (admin user, default groups, templates…)
cmd/es_init/                 — Elasticsearch index setup
cmd/notification-worker/     — RabbitMQ consumer
cmd/search-sync-worker/      — RabbitMQ consumer
cmd/snapshot-worker/         — RabbitMQ consumer (Yjs snapshot persistence)

internal/
  bootstrap/                 — chain-style Initializer (config → infra → repos → services)
  config/                    — Viper TOML loader; GlobalConfig singleton
  transport/connectserver/   — HTTP mux, Connect RPC handler wiring, auth interceptor, CORS
  transport/grpcserver/      — per-service RPC implementations (calls into service layer)
  service/<domain>_service/  — business logic; package-level singletons (*Svc)
  service/interface/         — service interfaces + MQ consumer contract
  service/mq_service/        — MQ abstraction init (RabbitMQ)
  repository/<domain>_repo/  — GORM queries; constructed via repository.NewRepositories()
  model/                     — GORM model definitions (16 models)
  dto/ mapper/ types/        — transfer objects, mapping helpers, domain types
  status/                    — typed error codes (status.GenErrWithCustomMsg)

pkg/
  storage/                   — infra clients: DB, KVS (Redis), MinioClient, ES, Consul (package-level globals)
  mq/                        — MQ interface + RabbitMQ impl
  cache/ lock/ key/          — shared cache keys, distributed lock, cache helpers
  errs/ constant/            — shared errors and constants

Build & Run

# Full dev stack (from repo root):
bash deploy/script/start.sh dev up

# Run backend only (after infra is up):
go run ./cmd/main.go

# Run individual workers:
go run ./cmd/snapshot-worker
go run ./cmd/notification-worker
go run ./cmd/search-sync-worker

# Migrate + seed (runs automatically in container):
go run ./cmd/migrate && go run ./cmd/db_init && go run ./cmd/es_init

No Makefile, no tests, no linter config. Verify with go build ./... and go vet ./....

Config

File: config.toml (gitignored) — generated from config.toml.tmpl by deploy/script/prepare.sh
Format: TOML, loaded by Viper with ${ENV_VAR} substitution
Env vars defined in deploy/.env (template: deploy/.env.example)
Access via config.GlobalConfig.*

Startup Order

Container CMD: migrate → db_init → es_init → main Workers are separate binaries with their own bootstrap chains.

Key Patterns

Connect RPC (not raw gRPC server): handlers in connectserver/handlers.go wrap grpcserver/* implementations
Two HTTP listeners: gRPC on grpc_port (9090), gRPC-web on grpc_web_port (8080); both use h2c
Auth interceptor: JWT-based; allowlist for Login, Register, Health, SystemInfo
Service singletons: auth_service.AuthSvc, document_service.DocumentSvc, etc. — set in service.Init()
Global infra: storage.DB, storage.KVS, storage.MinioClient, storage.ES, storage.Consul
Migration: GORM AutoMigrate (schema from model structs) + raw SQL for Postgres extensions (ltree) and indexes
DB seeding: cmd/db_init/ creates admin user, default permissions, templates, user groups
Elasticsearch: optional — InitElasticsearchAllowFail degrades gracefully
Consul: required — RequireConsulEnabled fatals if disabled
MQ: RabbitMQ via pkg/mq; workers consume topics registered through mq_service

Protobuf

Single proto: proto/yoresee_doc/v1/yoresee_doc.proto Consumes Go stubs (yoreseedocpb) from git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go, pinned to tag v0.1.0. No local codegen. Regenerate and publish the SDK after editing the .proto file.

Health Endpoints

/health — liveness
/readyz — readiness (checks DB + Redis)
/livez — liveness alias

4.0 KiB Raw Blame History