# INTERNAL SERVICES KNOWLEDGE BASE

## OVERVIEW
`internal/` hosts independent services used by the TiDB Cloud regional control plane. Each service is its own Go module with isolated build/test flows.

## STRUCTURE
```text
internal/
├── dataplane-manager/    # K8s and cloud infrastructure orchestration
├── dataplane-exporter/   # Dataplane-scoped metrics exporting service
├── capacity-planner/     # Metrics-driven autoscaling decisions and execution
├── ticdc-service/        # TiCDC lifecycle operator
├── k8s-version-manager/  # K8s version upgrade orchestration
├── cluster-agent/        # In-cluster control/exec agent
├── service-proxy/        # HTTP proxy and connectivity checks
├── audit-ng/             # Audit/slow-log upload sidecar
├── alicloud-pca-issuer/  # cert-manager issuer for AliCloud PCA
└── audit-kong/           # Kong plugin binary
```

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Cloud/K8s infra issue | `dataplane-manager/pkg/controllers/` | AppBox/VPC/Bucket task pipelines |
| Dataplane metrics exporter behavior | `dataplane-exporter/pkg/` | node attribution, snapshot readers, Prometheus exporters |
| Dataplane autoscaling decisions or execution | `capacity-planner/` | Start with [`capacity-planner/AGENTS.md`](capacity-planner/AGENTS.md) |
| TiCDC reconcile flow | `ticdc-service/controllers/ticdc/` | Task orchestration lives in `task/` |
| Upgrade operation logic | `k8s-version-manager/internal/controllers/upgradeoperation/` | Phase/step state machine |
| In-cluster command execution | `cluster-agent/service/` | API handlers and request validation |
| Proxy routing/checker | `service-proxy/pkg/` | Route matching, proxy, checker, audit |
| Audit upload behavior | `audit-ng/server/` | Rotation, push, cleanup loop |
| Cert issuer behavior | `alicloud-pca-issuer/pkg/` | Controller and signer integration |

## CONVENTIONS (INTERNAL ONLY)
- Service-local workflow: run `make` targets in each service directory; there is no single `internal/` Makefile.
- Toolchain versions differ by module (`.golangci.yml`, envtest/controller-gen versions, mock generators).
- Generated files are committed in multiple services (`zz_generated.deepcopy.go`, `pkg/*/mocks`, swagger clients).
- Some modules include local `AGENTS.md`/`CLAUDE.md`; follow the nearest one first, then parent guidance.

## ANTI-PATTERNS
- Editing generated artifacts directly (deepcopy, mockgen, go-swagger output) instead of regenerating.
- Assuming command parity across services (for example `make test` semantics differ by module).
- Mixing service ownership boundaries (for example modifying `dataplane-manager` logic for a `ticdc-service` bug without tracing integration path).
- Treating `internal/` as one Go module; each subservice has its own `go.mod` and dependency graph.

## COMMANDS
```bash
# Discover service modules quickly
rg --files -g "**/go.mod" .

# Run unit tests service-by-service
(cd dataplane-manager && make test)
(cd ticdc-service && make test)
(cd k8s-version-manager && make test)
(cd cluster-agent && make test)
(cd service-proxy && make test)
(cd audit-ng && make test)
(cd alicloud-pca-issuer && make test)
```

## HIERARCHY
- This file defines cross-service guardrails.
- Child files should only capture local deltas and must not repeat this file verbatim.
- Current child AGENTS coverage:
  - `dataplane-manager/AGENTS.md`
  - `capacity-planner/AGENTS.md`
  - `ticdc-service/AGENTS.md`
  - `k8s-version-manager/AGENTS.md`
  - `cluster-agent/AGENTS.md`
  - `service-proxy/AGENTS.md`
  - `audit-ng/AGENTS.md`

## NOTES
- There is no `.github/workflows` tree under `internal/`; CI pipelines are configured from the repository root.