Helps develop and maintain the DUW Queue Monitor notification system for Dolnośląski Urząd Wojewódzki queue status
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.
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
**Queue Monitor Service** (`cmd/queuemonitor/main.go`):
**Telegram Bot Service** (`cmd/telegrambot/main.go`):
**Shared Components**:
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
```
Use conventional commit format: `{type}({scope}): {description}`
**Common types**:
**Example**: `build(queue-monitor): add ca certs to image`
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
**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}`
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/duw-queue-monitor-development-assistant/raw