# Repository Guidelines

## Project Structure & Module Organization
This repository implements the Cloud FinOps pipeline: collectors gather cloud and billing data, analysts derive optimization or cleanup signals, actors apply approved actions, and reporters publish results.

- `collector/`: Python jobs for CloudQuery, Kubecost, Prometheus, and cluster metadata.
- `analyst/`: analysis code for leaks, labels, network cleanup, and shared helpers in `analyst/libs/`.
- `actor/`: automation for labels, cluster/resource-pool cleanup, EIP/network recycling, and manifests.
- `reporter/resource_platform/`: Umi/React dashboard published to the internal resources insight site.
- `tests/`: pytest tests mirroring source areas; `testdata/` and `data/` hold fixtures and static inputs.
- `.github/workflows/`: CI plus scheduled and manual operational workflows.

## Build, Test, and Development Commands
- `make install`: install root Python dependencies from `requirements.txt`.
- `pytest ./`: run the Python test suite locally.
- `pytest ./ --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html`: match CI.
- `make daily-kubecost`: collect and analyze the Kubecost daily asset snapshot.
- `cd reporter/resource_platform && npm install && npm run dev`: run the dashboard locally.
- `cd reporter/resource_platform && npm run build`: build the Umi dashboard.
- `cd actor/recycler/cluster_recycler && make build`: build the cleanup Docker image.

## Coding Style & Naming Conventions
Use Python 3.10-compatible code. Follow existing Python style: 4-space indentation, `snake_case` modules and functions, small script entry points, and shared logic in package helpers. Do not manually edit generated protobuf files under `actor/recycler/cluster_recycler/pbgen/`.

For the dashboard, keep Umi pages in `src/pages/`, TypeScript/TSX components near their page code, and layout styles in `src/layouts/*.less`. No repo-wide formatter is configured, so match neighboring files.

## Testing Guidelines
Use pytest for Python tests. Name files `test_*.py`, classes `Test*`, and methods `test_*`, as in `tests/analyst/external_label_reconciler/`. Add fixtures in `tests/conftest.py` or `testdata/` when behavior depends on cloud snapshot shapes. Prefer focused tests for changed analysis or actor behavior.

## Commit & Pull Request Guidelines
Recent commits use short imperative summaries such as `fix bigquery regions`, `support more regions...`, and `cleanup starter and essential clusters`. Keep the first line concise and mention the subsystem when useful.

Pull requests should describe the changed workflow or data path, include test/build evidence, link related issues or workflow runs, and include screenshots for dashboard UI changes.

## Security & Configuration Tips
Many scripts touch AWS, GCP, Kubernetes, Pulumi, S3, and CloudFront resources. Do not commit credentials, sensitive cloud dumps, or local kubeconfig/auth output. Prefer GitHub Actions secrets and local environment variables.