# Repository Guidelines

## Project Structure & Module Organization
- services/: Rust microservices and UIs.
  - Rust: `backend-api/`, `data-collector/`, `events-relay/`, `json-generator/`, `shared-lib/`, `build-orchestrator/`, `edge-agent/`.
  - Frontends: `frontend-admin/` (admin dashboard), `frontend-pwa/` (field PWA), `landing/`.
- infrastructure/: Nginx, Mosquitto, Postgres, seed data, test helpers.
- tests/: End‑to‑end Modbus simulation and helpers.
- docs/: Architecture, deployment, and security references.

## Build, Test, and Development Commands
- Rust workspace:
  - Build all: `cargo build --release`
  - Run a service: `cargo run -p backend-api`
  - Test all or per crate: `cargo test` or `cargo test -p shared-lib`
- Frontends (run from each app folder):
  - Install: `npm install`
  - Dev server: `npm run dev`
  - Build: `npm run build`
  - Lint: `npm run lint`
- Docker (local stack):
  - Start: `docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
  - Rebuild images: `docker compose build`


## Coding Style & Naming Conventions
- Rust: format with `cargo fmt`; 4‑space indent; `snake_case` for files/functions, `PascalCase` for types; keep modules small and reuse `services/shared-lib`.
- TypeScript/React: 2‑space indent; `PascalCase` components, `camelCase` hooks/utilities; prefer named exports; colocate UI in `src/features/...`.
- Linting: Rust via `cargo fmt -- --check`; Frontend via ESLint (`npm run lint`).

## Testing Guidelines
- Rust: add unit/integration tests near code; aim for meaningful coverage on domain logic in `shared-lib`. Run with `cargo test`.
- E2E: Python utilities under `tests/modbus_end_to_end/` for Modbus and mock backend; run individually, e.g., `python tests/modbus_end_to_end/modbus_sim_minimal.py`.
- Infra checks: MQTT auth script at `infrastructure/tests/test_mqtt_auth.py`.

## Commit & Pull Request Guidelines
- Commits: short, imperative, scoped. Examples: `feat(admin): tanks inventory`, `fix(edge): MQTT reconnect`, `docs: update DEPLOYMENT`.
- PRs: include purpose, linked issue, test notes (commands), and screenshots for UI. Keep changes focused; update docs when behavior changes.

## Security & Configuration Tips
- Never commit secrets. Start from `.env.example` and keep `.env` local.
- Use Docker Compose defaults; expose ports only via `docker-compose.dev.yml`.
- Follow docs in `docs/` for deployment, data flow, and hardening.