# Repository Guidelines

## Project Structure & Module Organization
- `main.go`: application entrypoint (HTTP server).
- `internal/`: core app code by layer:
  - `server/` (HTTP handlers/routes), `service/` (business logic), `repository/` (data access), `driver/` (external integrations), `config/` (env config), `view/` (templ views/viewmodels).
- `internal/view/*.templ` are source templates; generated files are `internal/view/*_templ.go`.
- `cmd/cron/`: cron entrypoint.
- `assets/`: static assets. `docs/`: documentation/images. `scripts/` and `tmp/`: tooling/artifacts.
- Tests live next to code as `*_test.go`.

## Build, Test, and Development Commands
- `make dev`: run local dev stack with Docker Compose and hot reload.
- `make run`: build and run production image locally.
- `make test`: run `go test ./...`.
- `make format`: run `templ generate`, `templ fmt`, and `go fmt`.
- `make lint`: run `golangci-lint run ./...`.
- `make stop`: stop dev containers.
- Local (without Docker): `go run .`, `go test ./...`.

## Coding Style & Naming Conventions
- Go style is standard `go fmt` (tabs, canonical imports).
- Package names: lowercase, no underscores.
- File names: lowercase with underscores when needed.
- Exported identifiers: `PascalCase`; unexported: `camelCase`.
- Keep handler/controller code thin; place business rules in `internal/service`.

## Testing Guidelines
- Use Go `testing` with table-driven tests where practical.
- Name files `*_test.go`; tests `TestXxx`; benchmarks `BenchmarkXxx`.
- Cover success and failure paths for changed logic.
- Run `make test` (or `go test ./...`) before opening a PR.

## Commit & Pull Request Guidelines
- Prefer Conventional Commits: `feat(scope): ...`, `fix(scope): ...`, `chore: ...`.
- Keep commits focused and atomic.
- PRs should include: clear summary, linked issue (e.g., `#51`), and screenshots for UI changes.
- Call out config/env changes and any migration or deployment impact.

## Security & Configuration Tips
- Config is environment-driven with `APP_` prefix (see `internal/config/config.go`).
- Example parser model override: `APP_OPENAI_MODEL=gpt-5-nano`.
- Never commit secrets; keep them in local `.env` / deployment secret manager.