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.

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.

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.

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.

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.

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.