GoTracker

GoTracker is a small Go service for creating and reading orders with a production-style delivery path:

• PostgreSQL stores the source of truth.
• Redis accelerates GET /orders/{id}.
• Kafka receives order-created events.
• Transactional outbox keeps order writes and event publishing consistent.

Stack

• Go
• PostgreSQL
• Redis
• Apache Kafka
• Docker Compose
• sqlx
• go-redis/v9
• segmentio/kafka-go
• golangci-lint
• goose

Architecture

Synchronous path

• POST /orders writes the order to PostgreSQL.
• GET /orders/{id} checks Redis first, then falls back to PostgreSQL.
• PUT /orders/{id} updates PostgreSQL and refreshes Redis.

Asynchronous path

• Order creation writes both orders and outbox_events in one transaction.
• The relay polls pending outbox rows.
• Kafka producer sends the event to the orders topic.
• The consumer reads the event and logs it.

Project Layout

gotracker/
├── cmd/
│   ├── api/                 # HTTP API entrypoint
│   └── consumer/            # Kafka consumer entrypoint
├── internal/
│   ├── cache/               # Redis cache layer
│   ├── http/                # HTTP handlers
│   ├── order/               # Domain model
│   ├── queue/               # Kafka + outbox relay
│   ├── repository/          # PostgreSQL access
│   └── service/             # Business logic
├── migrations/              # Goose migrations
├── docker-compose.yml       # Full local stack for app + dependencies
├── Dockerfile               # Multi-stage image build for API and consumer
├── Makefile                 # Common developer commands
└── .github/workflows/ci.yml # GitHub Actions pipeline

Quick Start

Option 1. Run everything with Docker Compose

1. Start the full stack:

make compose-up

2. Check containers:

docker compose ps

3. Check health:

curl -i http://localhost:8080/health

4. API is available at http://localhost:8080.

5. Stop the stack when you are done:

make compose-down

Option 2. Run services locally with Go

1. Create a local .env from .env.example.
2. Start only infrastructure:

make compose-up-infra

3. Install Goose and apply migrations:

go install github.com/pressly/goose/v3/cmd/goose@latest
make migrate

4. Install golangci-lint if you want to run make lint locally:

go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2

5. Run the API:

make run

6. In another terminal, run the Kafka consumer:

make run-consumer

Make Targets

make help
make build
make image-build
make run
make run-consumer
make test
make lint
make fmt
make migrate
make migrate-status
make migrate-down
make compose-up
make compose-up-infra
make compose-down

API Examples

Create an order:

curl -i -X POST http://localhost:8080/orders \
  -H "Content-Type: application/json" \
  -d '{"name":"Петя","address":"ул. Ленина, 1","is_delivered":false}'

Get all orders:

curl -i http://localhost:8080/orders

Get one order:

curl -i http://localhost:8080/orders/1

Update an order:

curl -i -X PUT http://localhost:8080/orders/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Петя","address":"ул. Пушкина, 99","is_delivered":true}'

Check application health:

curl -i http://localhost:8080/health

What to Watch in Logs

• API logs show Redis cache hit, miss, and cache write failures.
• GET /health shows whether PostgreSQL and Redis are currently available.
• API logs also show the outbox relay processing loop.
• Consumer logs show created order events received from Kafka.

Docker Notes

• make compose-up builds and starts PostgreSQL, Redis, Kafka, migrator, API, and consumer.
• The migrate service applies Goose migrations before the API starts.
• Local .env is still useful for make run and make migrate.
• Docker Compose uses internal hostnames such as postgres, redis, and kafka for container-to-container communication.

CI

GitHub Actions runs on push and pull request and performs:

• make test
• make build
• golangci-lint

The workflow file lives in .github/workflows/ci.yml.