# Repository Guidelines

## Project Structure & Module Organization
- `src/BCards.Web` is the main MVC app (Controllers, Services, Repositories, Razor Views, `wwwroot` assets).
- `src/BCards.IntegrationTests` spins up the site with fixtures for API-level checks.
- `tests/BCards.Tests` hosts xUnit + Moq unit coverage with overrides in `appsettings.Testing.json`.
- `tests.e2e` carries Playwright specs and config; utility scripts live under `scripts/`, with `clean-build.sh` mirroring CI cleanup.

## Build, Test & Development Commands
- `dotnet restore && dotnet build BCards.sln` primes dependencies and compiles.
- `dotnet run --project src/BCards.Web` launches the site (HTTPS on 5001 by default).
- `dotnet test` executes unit + integration suites; add `--collect:"XPlat Code Coverage"` to emit coverlet results.
- In `tests.e2e`, run `npm install` once and `npx playwright test` per change; append `--headed` when debugging flows.
- `./clean-build.sh` removes stale `bin/obj` output before CI or release builds.

## Coding Style & Naming Conventions
- Use 4-space indents, file-scoped namespaces, PascalCase for types, camelCase for locals, and `_camelCase` for DI fields.
- Keep Razor views presentation-only; push logic into Services, ViewModels, or TagHelpers.
- Store localization strings in `Resources/`, shared UI in `Views/Shared`, and bundle-ready assets in `wwwroot`.
- Run `dotnet format` before pushing; .NET 8 analyzers treat warnings as errors in the pipeline.

## Testing Guidelines
- Mirror namespaces when creating unit files (`FooServiceTests` for `FooService`) and favour FluentAssertions for expressiveness.
- Integration scenarios reside in `src/BCards.IntegrationTests/Tests`; use shared fixtures to mock MongoDB/Stripe without polluting global state.
- End-to-end cases focus on signup, checkout, and profile rendering; keep snapshots in `tests.e2e/debug_*`.
- Target ≥80% coverage across `Services/` and `Repositories/`; call out gaps explicitly in the PR body.

## Commit & Pull Request Guidelines
- Follow the observed `type: resumo` format (`feat: artigos & tutoriais`, `fix: checkout`); keep scopes short, Portuguese when public-facing.
- Squash WIP branches before review; one functional change per commit.
- Every PR needs a summary, verification list (`dotnet test`, Playwright when touched), related issue link, and UI artifacts when visuals change.
- Tag a module expert for review and flip the `Ready for QA` label only after E2E automation passes.

## Security & Configuration Notes
- Keep secrets out of version control; base new configs on `appsettings.Production.example.json` and document required keys.
- When callback URLs move, update both the environment files (`Dockerfile`, `docker-compose*.yml`) and external provider dashboards together.