# Repository Guidelines

## Project Structure & Module Organization
The service boots from `main.go`, and all Go packages live under `src`. Use `src/app` for orchestration, `src/domain` for entities and ports, `src/common` for shared helpers, `src/client/api/rest` for HTTP handlers and Swagger assets, and `src/cmd` for runnable entrypoints. Configuration samples live in `conf.toml`, `my_global_conf.toml`, and `res/`, while automation scripts sit in `build/` and `tools/`; vendor-locked dependencies remain in `vendor/` for reproducible builds.

## Build, Test, and Development Commands
- `make dev` – runs the contributor checklist plus lint gate before coding.
- `make check` – installs toolchains and executes golangci-lint, gosec, revive, errcheck, and dependency audits.
- `make test` – calls `go test ./...`; use `go test ./src/... -run TestName` for a focused run.
- `make build e=dev` – compiles via `tools/build.sh`; switch `e` to `prod`, `demo`, or `open-demo`.
- `QUANTEX_ENVIRONMENT="dev" go run main.go -c -run service` – starts the service with text logs (omit `-c` for JSON).
- `make deploy e=<alias>` – pushes a build using the target defined in `build/deploy.sh`.

## Coding Style & Naming Conventions
Run `make fmt` to apply gofumpt, gci, and goimports; Go’s formatter enforces tab indentation and canonical spacing. Follow idiomatic naming—PascalCase for exported symbols, camelCase for internals, lowercase filenames—and keep package paths under `quantex.com/qfixpt/<module>`. Group imports as standard library, third-party, then `quantex.com`, and avoid formatting-only commits.

## Testing Guidelines
Keep `*_test.go` files beside the code and prefer table-driven cases. Guard integration tests with `QUANTEX_ENVIRONMENT` so they hit the intended backend, and regenerate Swagger with `make swag` whenever REST contracts change. Spot-check concurrency with `go test -race ./src/<package>` and store fixtures under package-level `testdata/` directories.

## Commit & Pull Request Guidelines
Use `make branch t=<type> u=<user> n=<issue> m="summary"` to produce names such as `feature/jdoe/SKL-123/add_logger`. Write commit subjects in the imperative mood, referencing `SKL-###` when relevant. Pull requests must include a concise summary, linked issue, confirmation of `make test` and `make check`, and evidence (logs or screenshots) when altering responses or logging; call out configuration changes explicitly.

## Configuration & Deployment Tips
Treat `conf.toml` and `my_global_conf.toml` as templates and override secrets via environment variables. Confirm build metadata with `make print-version` before deploying, and promote builds through `make deploy e=<alias>`. When exploring logging formats pass `-f text|json|tint1|tint2`, and follow the `README.md` guidance for multi-DB runs that require elevated permissions.