DUW Queue Monitor Development Assistant

This skill helps you work with the DUW Queue Monitor codebase, a real-time notification system that monitors queue status at Dolnośląski Urząd Wojewódzki (DUW) and sends Telegram notifications when queues become available.

Project Architecture

The system consists of two Go microservices:

1. **queue-monitor**: Periodically checks queue status from the DUW API and sends notifications on status changes

2. **telegram-bot**: Telegram bot interface for user interactions and feedback collection

Key Components

**Queue Monitor Service** (`cmd/queuemonitor/main.go`):

**Telegram Bot Service** (`cmd/telegrambot/main.go`):

**Shared Components**:

Development Workflow

Building and Testing

1. **Build all packages**:

```bash

go build -v ./...

```

2. **Run all tests**:

```bash

go test -v ./...

```

3. **Run tests for a specific package**:

```bash

go test -v ./internal/queuemonitor

```

4. **Run a specific test**:

```bash

go test -v ./internal/queuemonitor -run TestQueueMonitor_CheckAndProcessStatus

```

5. **Build Docker image**:

```bash

docker build -t queue-monitor-test:latest -f cmd/queuemonitor/Dockerfile .

docker build -t telegram-bot-test:latest -f cmd/telegrambot/Dockerfile .

```

6. **Run Docker container locally** (requires environment variables):

```bash

docker run --rm queue-monitor-test:latest

```

Git Commit Convention

Use conventional commit format: `{type}({scope}): {description}`

**Common types**:

**Example**: `build(queue-monitor): add ca certs to image`

Instructions for AI Agent

When working with this codebase:

1. **Understand the state machine pattern**: The queue monitor uses `MonitorState` stored in Redis to track queue status changes. Only notify users on actual state transitions, not repeated states. Check `internal/queuemonitor/monitor.go` for state logic.

2. **Review existing tests before making changes**: Tests are located alongside source files with `_test.go` suffix. Integration tests use `testcontainers-go` for Redis testing (see `monitorstate_integration_test.go`).

3. **Follow dependency injection pattern**: Services are built through constructor functions that inject dependencies (logger, HTTP client, Redis client). This makes components testable and decoupled.

4. **Handle graceful shutdown**: Both services use `context.Context` with signal handling. Ensure new code respects context cancellation and saves state before shutdown.

5. **Configuration via environment variables**: All config is loaded from environment variables using `github.com/caarlos0/env/v11`. Add new config to the relevant struct and document required variables.

6. **Respect the data flow**:

- `Runner` orchestrates periodic checks

- `StatusCollector` fetches from DUW API with retries

- `QueueMonitor` compares states and triggers notifications

- State persists to Redis on each check and shutdown

7. **Testing approach**:

- Unit tests: Mock dependencies and test individual components

- Integration tests: Use testcontainers for Redis integration

- Run all tests before committing: `go test -v ./...`

8. **Infrastructure awareness**:

- Images are stored in Azure Container Registry: `acrduwshared.azurecr.io`

- Kubernetes manifests are in `infra/k8s/` (separate dev/prd configs)

- Terraform IaC is in `infra/terraform/`

- CI/CD workflows in `.github/workflows/`

9. **Kubernetes environments**:

- Development: `aks-duw-dev-plc`

- Production: `aks-duw-prd-plc`

- Use `kubectx` to switch contexts

10. **Publishing workflow**:

- Manually triggered via GitHub Actions

- Builds and pushes Docker image to ACR

- Creates git tag: `{service}-{version}`

- Inputs: service name (queue-monitor/telegram-bot), semantic version

Common Tasks

**Adding a new Telegram command handler**:

1. Create handler file in `internal/telegrambot/handlers/`

2. Implement handler function with signature: `func(ctx context.Context, b *bot.Bot, update *models.Update)`

3. Register handler in `internal/telegrambot/registry.go`

4. Update bot profile in `internal/telegrambot/profile.go` if needed

**Modifying queue status logic**:

1. Review current state machine in `internal/queuemonitor/monitor.go`

2. Update `MonitorState` struct if new state fields are needed

3. Modify state comparison logic in `CheckAndProcessStatus()`

4. Update notification messages in `createNotificationMessage()`

5. Add tests for new state transitions

6. Ensure Redis state persistence handles new fields

**Debugging production issues**:

1. Check Kubernetes logs: `kubectl logs -f deployment/{service} -n {namespace}`

2. Verify Redis state: Connect to Redis pod and inspect monitor state keys

3. Review recent commits and deployments

4. Check external API availability (DUW API)

**Deployment process**:

1. Merge PR to main (triggers tests)

2. Run publish workflow with service name and version

3. Update Kubernetes manifest with new image tag

4. Apply manifest: `kubectl apply -f infra/k8s/{deployment}.yml`

5. Monitor rollout: `kubectl rollout status deployment/{service} -n {namespace}`

Constraints