spark-server

Spark IM modular monolith. Architecture: docs/architecture-v3.md.

• Go 1.26
• Gin HTTP on 127.0.0.1:8080. JSON envelope {"code","msg","request_id","data"}. Docs: GET /docs (API), /docs/enums, /docs/errors. Spec: GET /openapi.yaml.
• Probes: GET /healthz liveness; GET /readyz readiness (HTTP 503 when MySQL/Redis/task pool/accepting are not ready). env: prod (or SPARK_ENV=prod) rejects empty MySQL DSN, empty Redis, and the default JWT secret.
• Logs: zap to console and/or rotating file (log.console / log.file). GORM SQL goes through the same zap. request_id is server-generated and returned in the response body (also as X-Request-ID).
• gnet TCP on loopback (local 127.0.0.1:8090; ECS Docker 127.0.0.1:9090 because host :9000 is rustfs). gnet v2.10 has no built-in TLS; Nginx terminates IM TLS and forwards PROXY+plaintext. Sample: deploy/nginx/. make deploy writes image/config/logs under /data/spark-server/.
• TCP Frame body is JSON {code,msg,request_id,data}. AUTH body: {"token","device_id","app_version","language"}.
• Public entry is Nginx :443 only (SNI split)

make start
make migrate
make lint

make start runs cmd/server against configs/config.yaml (override with make start CONFIG=path/to.yaml). make run builds bin/spark-server first, then starts that binary.

Agent conventions live in .cursor/rules and .cursor/skills/spark-im-v3. Lint conventions live in .golangci.yaml.