CLAUDE.md

Notes for Claude Code when working in this repo.

Vai trò của repo này

football-booking-gitops là GitOps source of truth: ArgoCD Application/ApplicationSet + Helm chart cho mọi workload (NestJS backend, chatbot Python, Go services) trên K3s cluster. Repo này không chứa source code app — chỉ chứa manifest/chart trỏ tới image đã build sẵn ở GHCR.

Khi làm việc ở đây, đóng vai GitOps/platform engineer: mọi thay đổi ở đây tác động trực tiếp tới cluster production qua ArgoCD auto-sync — không có môi trường staging riêng để thử trước. Luôn kiểm tra kỹ values.yaml/ image tag trước khi commit, vì sai sót ở đây (vd: sai image tag, sai port) sẽ được ArgoCD apply gần như ngay lập tức.

Tài liệu tham khảo trước

Kiến trúc + cách hoạt động: README.md (mục "How It Works")
Hướng dẫn ArgoCD: docs/argocd-guide.md
Quyết định kỹ thuật đã có: docs/adr/

Architecture Decision Records (ADR)

Dùng docs/adr/ làm nhật ký quyết định. Khi thực hiện một trong các việc sau, PHẢI tạo/cập nhật ADR (dùng docs/adr/template.md) trước khi implement:

Thêm 1 chart type mới trong charts/ (runtime khác Node/Python/Go), hoặc đổi cấu trúc chart dùng chung hiện có
Đổi cách ArgoCD Application/ApplicationSet được tổ chức (vd: gộp/tách ApplicationSet theo domain)
Đổi flow cập nhật image tag (hiện tại: CI commit trực tiếp vào envs/production/<service>.yaml) — vd: chuyển sang ArgoCD Image Updater
Thêm môi trường mới ngoài envs/production (staging, canary...)
Đổi chiến lược rollout/rollback (hiện tại: git revert + auto-sync)

Không cần ADR cho: bump image tag thường ngày (do CI tự làm), sửa values.yaml một field cấu hình (replica count, resource limit) theo nhu cầu vận hành thông thường.

Quy tắc: đánh số tuần tự NNNN-slug.md, không sửa ADR đã Accepted (tạo bản mới + Supersedes/Superseded by), cập nhật bảng trong docs/adr/README.md.