# Repository Guidelines

## Project Structure & Module Organization

- `main.go`: Application entrypoint (HTTP server on `:8000`).
- `internal/`: Private app code (e.g., `server/`, `service/`, `repository/`, `driver/`,
  `config/`, `view/`). Templ views live in `internal/view` and generate `*_templ.go`.
- `pkg/`: Reusable packages shared across app layers.
- `cmd/`: Optional binaries/entrypoints.
- `assets/`: Static assets and images.
- `docs/`: Project documentation.
- `scripts/`, `tmp/`: Dev tooling and build artifacts (Air uses `tmp/`).

## Build, Test, and Development Commands

- `make dev`: Start dev container with live reload (Air) on `http://localhost:8000`.
- `make run`: Build and run the Docker image with `PORT` and `DATABASE_URL`.
- `make test`: Run `go test ./...` inside the running dev container.
- `make format`: Run `templ generate`, `templ fmt`, and `go fmt`.
- `make lint`: Run `golangci-lint`.
- Local alternative: `air -c .air.toml`, `go test ./...`, `go run .`.

## Coding Style & Naming Conventions

- Go formatting: Use `go fmt` (tabs, standard import ordering). CI helpers:
  `make format`.
- Linting: `golangci-lint run ./...` via `make lint` (fix issues before PR).
- Packages: lowercase, no underscores; files: lowercase with underscores; exported
  identifiers: `PascalCase`; unexported: `camelCase`.
- Templ: keep `.templ` in `internal/view`; commit sources, not generated `*_templ.go`.

## Testing Guidelines

- Framework: standard `testing` with table-driven tests.
- Files: `*_test.go`; functions: `TestXxx`, benchmarks: `BenchmarkXxx`.
- Run: `make test` (in container) or `go test ./...` locally.
- Aim for meaningful coverage on new/changed code; include error paths.

## Commit & Pull Request Guidelines

- Messages: Prefer Conventional Commits (e.g., `feat(parser): ...`,
  `fix(config): ...`). Short, imperative first line; scope optional.
- PRs: Provide clear description, link issues (e.g., `#45`), include screenshots
  for UI, and note breaking changes/migrations.
- Keep diffs focused; run `make format` and `make lint` before opening.

## Security & Configuration Tips

- Environment: Use `.env`/`prod.env`; never commit secrets.
  Example: `DATABASE_URL="host=... user=... database=..."`.
- Ports: default `8000`; configure via `PORT`.
- Dependencies: use `go mod tidy` and `make up-deps` when updating.