Agent-native repository documentation

Adds CLAUDE.md, a single instruction file that tells AI coding agents how to work in this
repository, plus AGENTS.md as a symlink to it so tools that look for either filename find the same
content. The document is deliberately vendor-neutral — no assistant-specific syntax, commands or
configuration — so any agent can consume it.

What it covers

• Makefile-first workflow. A per-task table mapping each job to its make target, and the flags
  you silently lose by calling the underlying tool directly (make test adds -race -covermode atomic; make swag-v1 passes --parseDependency -g internal/controller/restapi/router.go;
  make format runs go fix, gofumpt and gci with the repo's import grouping).
• Layer boundaries. The dependency direction across entity → usecase → repo →
  controller, the rule that pkg/ never imports internal/, and that wiring happens only in
  internal/app/app.go.
• Where new code goes. A decision table keyed on what the code knows about — a domain
  invariant, SQL, an HTTP status, a reusable server — plus file, package and constructor naming
  conventions.
• The handler contract. The six steps every controller method follows on all four transports:
  identify the caller, decode into a transport-local DTO, validate, call the use case with the
  request context, map sentinel errors to a transport status, encode the response.
• Checklists. Adding a use case to an existing domain, and adding a whole domain end to end
  from entity and migration through repository, use case, mocks, wiring, transports, docs and
  integration test.
• Translation upkeep. README.md is canonical; README_RU.md and README_CN.md mirror it
  section for section, with a trigger table for which change requires which README edit and rules
  for localized anchors.
• Generated artifacts. Which files come from make swag-v1, make proto-v1 and make mock,
  and must never be hand-edited.

Documented pitfalls

• make integration-test runs on the host and always fails; make compose-up-integration-test is
  the real entry point.
• make migrate-create <name> prints No rule to make target after succeeding — a side effect of
  reading the name from MAKECMDGOALS.
• make run and make pre-commit require swag and protoc on PATH; make bin-deps does not
  install protoc.
• Fiber handlers must use ctx.UserContext(), never ctx.Context(), or the trace is dropped.
• Every use-case and repository constructor returns the interface wrapped by newTraced, so a new
  contract method must be implemented in three places — interface, struct and tracing decorator.
• internal/repo/persistent/translation/ declares package persistent while its siblings use the
  directory name; new packages should follow task/ and user/.

What's Changed

• chore(deps): security updates by @soltanoff in #475
• feat: AI native docs for agents by @soltanoff in #476

Full Changelog: v1.17.2...v1.18.0

v1.18.0 Latest

Latest

Compare

Choose a tag to compare

What's Changed

• chore(deps): security updates by @soltanoff in #462

Full Changelog: v1.17.1...v1.17.2

v1.17.2

Compare

Choose a tag to compare

What's Changed

• chore(deps): security updates by @soltanoff in #457

Full Changelog: v1.17.0...v1.17.1

v1.17.1

Compare

Choose a tag to compare

Distributed Tracing with OpenTelemetry

End-to-end distributed tracing across the entire request path, powered by OpenTelemetry. A single trace now spans all four transports and every architectural layer: controller -> usecase -> repo. It's exported over OTLP/gRPC to a collector (Jaeger in the docker stack).

What's new

• OTLP/gRPC exporter - a global TracerProvider (pkg/tracing) with configurable endpoint, TLS, and sampling; spans batch-export to any OTLP-compatible backend.
• Cross-transport context propagation - W3C traceparent + baggage, so traces stay connected regardless of transport:
  • REST -> otelfiber middleware
  • gRPC -> otelgrpc stats handler
  • AMQP RPC / NATS RPC -> trace context carried in message headers via custom carriers
• Instrumented business layers -> use cases and repositories wrapped in tracing decorators, giving full visibility from handler down to DB and external web API calls.
• Jaeger in the docker stack -> make compose-up-all now brings up Jaeger, reachable through the nginx reverse proxy.
• No-op when disabled -> with TRACING_ENABLED=false, a no-op tracer provider is installed; instrumentation runs unconditionally with zero overhead.
• Internal routes excluded -> /healthz, /metrics, /swagger are not traced; only versioned API groups are instrumented.

Configuration

⚠️ Sampling is parent-based - use 1.0 locally, but keep it low (0.1 / 0.01) in production.

Upgrade notes

• Tracing is off by default - no action required to keep current behavior. To enable, set TRACING_ENABLED=true and point TRACING_OTLP_ENDPOINT at your collector.
• Persistent repos were reorganized into per-domain packages to host the tracing decorators; the composition root was updated accordingly. No public API or transport contract changes.

PR's

• feat(OTEL): OTEL/OTLP integration by @soltanoff in #452

Full Changelog: v1.16.4...v1.17.0

v1.17.0

Compare

Choose a tag to compare

What's Changed

• chore(deps): go1.26.5 and security updates by @soltanoff in #450
• chore(docker): remove version specification from docker-compose files by @soltanoff in #451

Full Changelog: v1.16.3...v1.16.4

v1.16.4

Compare

Choose a tag to compare

What's Changed

• chore(deps): go1.26.4 and security updates by @soltanoff in #439

Full Changelog: v1.16.2...v1.16.3

v1.16.3

Compare

Choose a tag to compare

What's Changed

• chore(deps): go1.26.3 and security updates (CVE-2026-42501) by @soltanoff in #431

Full Changelog: v1.16.1...v1.16.2

v1.16.2

Compare

Choose a tag to compare

What's Changed

• feat: update README to reflect addition of NATS RPC and enhance domain descriptions by @soltanoff in #407
• chore(deps): update dependencies and modify linting rules by @soltanoff in #421
• refactor: make nested config structs unexported by @Dawe257 in #419
• chore(ci): update linting actions to use fail_level for error reporting by @soltanoff in #422

New Contributors

• @Dawe257 made their first contribution in #419

Full Changelog: v1.16.0...v1.16.1

v1.16.1

Compare

Choose a tag to compare

What's New: User Authentication & Task Management

This release adds two major domains to the clean architecture template — user authentication and task management — across all four transport layers (REST, gRPC, RabbitMQ RPC, NATS RPC).

User Authentication

• Registration with bcrypt password hashing and email uniqueness enforcement
• Login with JWT token generation and configurable expiry
• Auth middleware for all transport layers (Fiber, gRPC interceptor, AMQP/NATS token extraction)
• Profile endpoint to retrieve the authenticated user

Task Management

• Full CRUD for tasks scoped to the authenticated user
• Status state machine with validated transitions: todo → in_progress → done (and in_progress → todo)
• List endpoint with pagination (limit/offset) and optional status filtering
• Ownership enforcement — users can only access their own tasks

Infrastructure

• JWT package (pkg/jwt) with token generation and validation
• Three new database migrations: users table, tasks table, user_id foreign key on translation history
• gRPC server options support (for injecting unary interceptors)
• Protobuf definitions for auth and task services

Testing

• 27 unit tests for the task use case covering all operations and error paths
• Unit tests for user use case (register, login, get)
• Table-driven entity tests for task status transitions
• Auth middleware tests for both REST and gRPC
• Integration tests restructured into separate files by domain (user_test.go, task_test.go, translation_test.go)

Other Changes

• Swagger docs regenerated with full coverage of new endpoints
• Docker Compose updated with JWT configuration
• Logger simplified (removed redundant debug-level branching in error path)

Chore Changed and PR's

• chore(deps): bump rabbitmq from 4.2.4-management to 4.2.5-management by @dependabot[bot] in #397
• chore(deps): bump google.golang.org/grpc from 1.79.2 to 1.79.3 by @dependabot[bot] in #396
• chore(deps): bump github.com/jackc/pgx/v5 from 5.8.0 to 5.9.1 by @dependabot[bot] in #398
• chore(deps): bump nginx from 1.29.6-alpine to 1.29.7-alpine by @dependabot[bot] in #399
• chore(deps): bump github.com/nats-io/nats.go from 1.49.0 to 1.50.0 by @dependabot[bot] in #400
• chore(deps): update go-playground/validator, zerolog, grpc, and other by @soltanoff in #405
• feat: implement user authentication and task management with JWT support by @soltanoff in #406

Full Changelog: v1.15.2...v1.16.0

v1.16.0

Compare

Choose a tag to compare

What's Changed

• chore(deps): bump nginx from 1.29.5-alpine to 1.29.6-alpine by @dependabot[bot] in #392
• chore(deps): bump github.com/goccy/go-json from 0.10.5 to 0.10.6 by @dependabot[bot] in #393
• Bump golang from 1.26.0 to 1.26.1 by @soltanoff in #395

Full Changelog: v1.15.1...v1.15.2

v1.15.2

Compare

Choose a tag to compare