# TICDC-SERVICE KNOWLEDGE BASE

## OVERVIEW
`ticdc-service` has two runtime roles:
- `controller`: a Kubernetes controller that reconciles `TiCDC` CRs and deploys/manages TiCDC clusters on dataplane Kubernetes clusters.
- `http`: an API server process that runs internal gRPC services, an HTTP gRPC-gateway, and a metrics endpoint for TiCDC cluster, precheck, and sink-endpoint operations.

## STRUCTURE
- `cmd/main.go` and `internal/cmd/root.go`: binary entrypoint and Cobra command wiring.
- `internal/cmd/controller.go`: controller-runtime manager/bootstrap for the reconcile loop.
- `internal/cmd/http_service.go`: API server bootstrap for gRPC, gateway, and metrics.
- `internal/server/`: transport stack, middleware, and HTTP/metrics serving.
- `controllers/ticdc/controller.go`: reconcile loop and task orchestration.
- `controllers/ticdc/task/`: deploy/destroy tasks (`guardian`, `vac`, `cert`, `cluster`).
- `pkg/service/`: gRPC service implementations for TiCDC cluster, precheck, and sink-endpoint APIs.
- `pkg/`: providers and shared libs (`cloud`, `cdccluster`, `clusterproxy`, `regionalservice`, `service`).
- `api/v1/`: CRD types (`TiCDC`, generated deepcopy).
- `tests/integration/`: envtest-style integration tests.

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Command entrypoints | `internal/cmd/controller.go`, `internal/cmd/http_service.go` | choose the correct runtime before debugging |
| HTTP/gRPC server behavior | `internal/server/server_grpc.go` and `internal/server/middleware/` | gRPC registration, gateway wiring, metrics, middleware |
| Reconcile behavior | `controllers/ticdc/controller.go` | Task list and status/update flow |
| Task implementation | `controllers/ticdc/task/*.go` | Deploy/destroy step logic |
| Remote cluster apply | `pkg/k8s/` and `pkg/applier/` | Apply semantics and test patterns |
| Regional API calls | `pkg/regionalservice/` | SharedPool/dataplane metadata lookup |
| Runtime service layer | `pkg/service/` | API-facing logic served by the `http` command |

## COMMANDS
```bash
make build
make test
make integration
make test-e2e          # requires Kind cluster
make lint
make generate-mocks
make manifests
```

## CONVENTIONS (LOCAL)
- The binary has two different command paths (`controller` and `http`); verify which runtime owns the behavior before changing code or docs.
- Reconcile composes tasks in this order: `Guardian -> VolumeAttributesClass -> Certificate -> Cluster`.
- Status and spec updates are both part of reconcile; keep update order consistent with `controller.go` to avoid stale writes.
- The `http` command starts three pieces together: internal gRPC server, HTTP gateway, and metrics server.
- `make lint` runs with `--fix` and then `git diff --exit-code`; lint will fail if auto-fixes are not committed.
- Mock files under `pkg/**/mocks/` are generated via `make generate-mocks`.
- CRD generated files (`api/v1/zz_generated.deepcopy.go`) are source-generated.

## ANTI-PATTERNS
- Debugging API-serving behavior only from the controller path, or controller reconcile behavior only from the `http` path.
- Editing generated mocks/deepcopy files by hand.
- Changing task order in reconcile without checking destroy/deploy dependency impact.
- Running `test-e2e` without Kind bootstrap (target expects cluster availability).
- Copying outdated scaffold content from `README.md` TODO sections into implementation guidance.