# Repository Guidelines

PayIt is a Go-based Stripe integration demo. Use this guide to deliver focused contributions that keep the service reliable and secure.

## Project Structure & Module Organization

- `go.mod` defines the module `github.com/rjNemo/payit` and anchors dependencies; update it alongside any new package additions.
- Keep the HTTP server entry point in `cmd/payit/main.go`; additional CLIs belong under `cmd/<name>`.
- Place shared business logic under `internal/payments`, with Stripe client helpers in `internal/stripe`; keep packages small and unexported when possible.
- Organize web handlers, templates, and static assets under `internal/web`, `web/templates`, and `web/static`. Store sample data or fixtures beside the owning package under `testdata/`.

## Build, Test, and Development Commands

- Prefer the Makefile workflow for local checks; these commands set local caches so they work in sandboxed environments.
- After each code change run formatting, linting, and test suites via `make fmt lint test` to ensure consistency, coverage visibility, and to prevent cached results. If the Makefile is missing, create it before coding.
- After verifying changes, create a conventional commit (e.g., `feat: add checkout handler`) so the history captures intent and scope.
- `go run ./cmd/payit` — start the local server, loading configuration from `.env.local` when present.
- `go build ./...` — ensure every package compiles prior to opening a PR.
- `go test ./...` — execute the full unit suite; add `-run TestStripe` to focus on Stripe-specific tests during iteration.
- `STRIPE_SECRET_KEY=sk_test... go test ./internal/payments -v` — example of running package tests that require live credentials.

## Coding Style & Naming Conventions

Run `go fmt ./...` and `goimports` before committing; code should pass Go 1.25 formatting without manual tweaks. Name handlers `<Resource>Handler`, Stripe service wrappers `<Resource>Service`, and environment variables `PAYIT_*`. Centralize configuration defaults under `config/config.go` and prefer composition over inheritance-style embedding.

## Testing Guidelines

Write table-driven tests named `Test<Thing>_<Scenario>`. Co-locate doubles in `_test.go` files and keep external fixtures under `testdata/`. Target >80% coverage on payment flows, and gate integration suites behind the `-short` flag so CI can skip live Stripe runs when credentials are absent.

## Commit & Pull Request Guidelines

Use imperative, present-tense commits such as `feat: add checkout handler`; include a short body that explains why. Reference issues with `Refs #123` and note config or schema changes. PRs should summarize the change, attach manual test notes, and include screenshots or API logs when behavior shifts. Always wait for tests to pass before requesting merge.

## Security & Configuration Tips

Never commit Stripe secrets; store them in `.env.local` and rely on your process manager to inject them. Rotate exposed keys immediately. Redact cardholder data in logs and avoid persisting PII outside Stripe’s systems.