# Repository Guidelines

## Project Structure & Module Organization

This workspace contains two independently versioned applications:

- `fe-digitaltwin-v2/` is the React 18 + TypeScript frontend. Put routes in `src/pages/`, reusable UI in `src/shared/components/`, application features in `src/features/`, state in `src/store/`, and static files in `public/`.
- `be-ircfa/` is the Python 3.11+ FastAPI service. API domains live under `src/` (for example, `src/rag/` and `src/root_cause/`); keep each domain's router, model/schema, and service together. Tests live in `tests/`, with unit tests in `tests/unit/`.

Both directories have their own Git repository; run Git commands from the application being changed.

## Build, Test, and Development Commands

Run commands from the relevant application directory.

- `cd fe-digitaltwin-v2 && npm install` installs frontend dependencies.
- `npm run dev` starts Vite at port 3002; `npm run build` type-checks and creates the production bundle; `npm run lint` runs ESLint; `npm run preview` serves the built bundle.
- `cd be-ircfa && make install` installs Poetry dependencies, `make run` starts the service, and `make test` runs `pytest tests/unit/` with the project on `PYTHONPATH`.

## Coding Style & Naming Conventions

Follow the backend `.editorconfig`: four spaces, LF endings, trimmed trailing whitespace, and a final newline (tabs in `Makefile`). Use `snake_case` for Python modules and functions; group backend code by feature with files such as `router.py`, `service.py`, and `model.py`.

Use TypeScript for frontend changes. Components and page files use PascalCase (for example, `DashboardPage.tsx`); hooks use the `use-` / `use` pattern (for example, `use-debounce.tsx`). Prefer configured `@/` aliases over deep relative imports, and reuse existing design-system components and tokens. Run ESLint before submitting frontend changes.

## Testing Guidelines

Add or update backend pytest coverage alongside behavioral changes; name test files `test_*.py` and tests `test_*`. Run `make test` before review. The frontend currently exposes lint and production-build checks rather than a test script, so run both `npm run lint` and `npm run build` for frontend work.

## Commit & Pull Request Guidelines

Frontend history commonly uses Conventional Commit prefixes such as `feat:`, `fix:`, and `chore:`; use concise imperative subjects (for example, `feat: add RCFA export filter`). Keep commits scoped to one application and concern. Pull requests should explain the user-visible change, list validation performed, link the relevant issue when available, and include screenshots for UI changes. Do not commit secrets, local `.env` files, debug exports, or generated build output.