# Repository Guidelines

## Project Structure & Module Organization
Core MVC code lives in `Controllers`, `Services`, `Models`, and `Middleware`, while Razor views sit in `Views` and static assets in `wwwroot`. Data access and caching helpers are under `Data` and `Providers`. Localized resources (PT-BR, ES, EN) reside in `Resources`. Tests target service logic in `Tests/Services` via `QRRapidoApp.Tests.csproj`. Runtime settings use the `appsettings.*.json` files, and Docker assets, including `docker-compose.yml`, remain at the repository root.

## Build, Test, and Development Commands
Install dependencies with `dotnet restore`, then run `dotnet build` for a release-ready compile. Use `dotnet run` to launch the Kestrel server locally or `dotnet watch run` for hot reload during UI work. Execute `dotnet test` from the root to run xUnit tests; add `--collect:"XPlat Code Coverage"` when you need coverage reports. For full-stack parity, start infrastructure with `docker-compose up -d` and follow component logs through `docker-compose logs -f qrrapido`.

## Coding Style & Naming Conventions
Stick to standard C# styling: four-space indentation, PascalCase for types and public members, camelCase for locals, and `I` prefixes for interfaces. Keep services focused; prefer small, testable classes instead of partials. Place shared copy in `Resources` and surface it via `IStringLocalizer`. Run `dotnet format` before committing to normalize imports, analyzer fixes, and whitespace.

## Testing Guidelines
Keep unit and integration tests close to the subject, e.g., `Tests/Services/QRRapidoServiceTests.cs`. Name classes `<Subject>Tests` and methods as scenario sentences such as `GenerateRapidAsync_WithValidRequest_ReturnsSuccess`. Use Moq for external dependencies and configure defaults in constructor helpers. Every new behavior should gain at least one happy-path and one guard test, and maintain quick, deterministic fixtures.

## Commit & Pull Request Guidelines
Follow the Conventional Commit style observed here (`fix:`, `feat:`, `chore:`) with concise Portuguese summaries for user-facing updates. Group related changes per commit to simplify reversions. Pull requests should outline the context, enumerate key changes, attach `dotnet test` output or coverage deltas, and include UI screenshots or GIFs when behavior shifts. Reference Azure or GitHub issue IDs and call out configuration or migration steps prominently.

## Security & Configuration Tips
Never commit secrets or the contents of `keys/`. Document new configuration values in the PR description and supply safe defaults in `appsettings.Development.json`. Protect added endpoints with existing rate-limiting and authorization middleware, and rotate published test keys after demos.
