# Repository Guidelines

## Project Structure & Module Organization

This repository is currently a clean workspace with no application source tree checked in. Keep new code organized by responsibility:

- `src/` for application code and reusable modules.
- `tests/` for automated tests that mirror the `src/` layout.
- `assets/` for static images, fonts, fixtures, or other non-code resources.
- `docs/` for architecture notes, setup guides, and operational runbooks.

Prefer small, focused modules. Place shared helpers near the code that uses them first; promote them to a common module only when multiple features need them.

## Build, Test, and Development Commands

No build system or package manifest is currently present. When tooling is added, document the canonical commands in the README and keep them stable. Recommended command names:

- `npm run dev`, `pnpm dev`, or equivalent: start the local development server.
- `npm test`, `pnpm test`, or equivalent: run the full test suite.
- `npm run lint` / `npm run format`: check and format code style.
- `npm run build`: produce a production-ready build.

Avoid adding ad hoc scripts that only work on one machine. Prefer cross-platform commands or document platform-specific requirements clearly.

## Coding Style & Naming Conventions

Follow the formatter and linter configured by the first language/toolchain added to the project. Until then, use 2-space indentation for web projects, 4-space indentation for Python, and meaningful names over abbreviations.

Use clear file names that describe purpose, for example `user-service.ts`, `map-view.tsx`, or `test_user_service.py`. Keep public APIs explicit and avoid large catch-all utility files.

## Testing Guidelines

Add tests alongside each new feature or bug fix. Test files should mirror the implementation name, such as `user-service.test.ts` for `src/user-service.ts` or `test_user_service.py` for `src/user_service.py`.

Prefer fast unit tests for business logic and a smaller number of integration tests for workflows. Include regression tests for any fixed bug.

## Commit & Pull Request Guidelines

Git history is not available in this workspace, so use a simple imperative commit style: `Add project scaffold`, `Fix login validation`, `Update map assets`.

Pull requests should include a short summary, testing performed, linked issues when applicable, and screenshots or screen recordings for user-facing UI changes. Keep PRs focused; split unrelated changes into separate submissions.

## Security & Configuration Tips

Do not commit secrets, local credentials, generated build output, or machine-specific configuration. Store required environment variables in an ignored `.env` file and document safe example values in `.env.example`.

## Standard architektoniczny: routing (obowiązkowy)

Każdy nowy widok, ekran, zakładka lub podstrona **musi mieć własny, jednoznaczny adres URL** i być obsługiwana przez React Router. To twardy standard całego projektu, nie sugestia.

Zasady:

- **Nie buduj nawigacji na stanie.** Zakazane jako mechanizm przełączania stron: `useState('view')`, `setView`, `activeView`, `selectedPage`, `selectedTab` i pochodne.
- **Nie przełączaj całych stron warunkowym renderowaniem** bez zmiany adresu (`{view === 'x' && <Page />}`).
- **Do nawigacji używaj** `Link`, `NavLink`, `useNavigate` oraz tras zadeklarowanych w `Routes`.
- **Identyfikatory obiektów trzymaj w parametrach URL**: `/oferta/:id`, `/profil/:id`, `/wiadomosci/:conversationId` - nie w stanie Reacta.
- **Filtry, sortowanie, wyszukiwanie i paginację zapisuj w query string** wszędzie tam, gdzie użytkownik powinien móc skopiować lub odświeżyć widok.
- **Zakładki paneli twórz jako trasy zagnieżdżone**: `/konto/ustawienia`, `/admin/uzytkownicy`.
- **Trasy wymagające logowania zabezpieczaj `ProtectedRoute`** (`frontend/src/ProtectedRoute.tsx`). Pamiętaj, że to zabezpieczenie interfejsu - autoryzację egzekwuje backend.
- **Nie używaj `href="#"`** ani przycisków imitujących linki.
- **Każdy link musi działać** po odświeżeniu (F5), przy bezpośrednim wejściu z adresu, po użyciu Wstecz/Dalej i po otwarciu w nowej karcie.

Gdzie co leży:

- `frontend/src/routes.ts` - centralna mapa adresów (`ROUTES`) i helpery (`listingPath`, `mapPath`, `adminTabPath`). Nowy widok zaczynaj od wpisu tutaj, nie od literału ścieżki w JSX.
- `frontend/src/ProtectedRoute.tsx` - bramka autoryzacji, obsługuje stan `loading` z `AuthProvider`.
- `frontend/src/App.tsx` - deklaracja `<Routes>`.
- `nginx/default.conf` - `try_files $uri $uri/ /index.html` (SPA fallback, już skonfigurowany).

Przed zakończeniem każdego zadania sprawdź, czy dodane widoki mają trasy i czy adres zmienia się podczas nawigacji. Jeżeli istniejący kod łamie ten standard, nie powielaj starego rozwiązania - dostosuj go do React Routera.

## Behavioral Guidelines To Reduce Common LLM Coding Mistakes

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

### 1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them instead of choosing silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop, name what is confusing, and ask.

### 2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No flexibility or configurability that was not requested.
- No error handling for impossible scenarios.
- If code is much longer than needed, rewrite it to be simpler.

Ask: Would a senior engineer say this is overcomplicated? If yes, simplify.

### 3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

- Do not improve adjacent code, comments, or formatting unless needed for the task.
- Do not refactor code that is not broken.
- Match existing style, even if you would do it differently.
- If unrelated dead code is noticed, mention it but do not delete it.

When changes create orphans:

- Remove imports, variables, or functions made unused by your own changes.
- Do not remove pre-existing dead code unless asked.

Test: Every changed line should trace directly to the request.

### 4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

- Add validation -> write tests for invalid inputs, then make them pass.
- Fix a bug -> write a test that reproduces it, then make it pass.
- Refactor X -> ensure tests pass before and after.

For multi-step tasks, state a brief plan:

1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]

Strong success criteria enable independent execution. Weak criteria require frequent clarification.

These guidelines are working if there are fewer unnecessary diff changes, fewer rewrites caused by overcomplication, and clarifying questions appear before implementation mistakes.