1# AGENTS.md
  2
  3This file provides guidance to AI coding agents when working with code in this repository.
  4
  5## Project Architecture & Core Components
  6
  7This is an XMPP to SMS gateway for Bandwidth's V2 Messaging API (sgx-bwmsgsv2). The system consists of:
  8
  9**Core Services:**
 10- `sgx-bwmsgsv2.rb` - Main XMPP gateway using Blather DSL, handles XMPP→Bandwidth API communication
 11- `r2s-bwmsgsv2.rb` - Redis queue to HTTP request translator, processes pending messages
 12- `h2r-bwmsgsv2.php` - Helper script for HTTP to Redis operations
 13
 14**Key Libraries:**
 15- `lib/bandwidth_error.rb` - Custom error handling for Bandwidth API responses
 16- `lib/registration_repo.rb` - Redis-backed registration management with conflict detection
 17- `bin/notify_inbound_failures_job` - Background job for handling inbound message failures
 18
 19**Architecture Notes:**
 20- Uses EventMachine for async operations throughout
 21- Redis for message queuing and registration storage
 22- Bandwidth API V2 integration with proper error handling
 23- XMPP protocol via Blather gem (custom fork from develop branch)
 24
 25## Development Commands & Workflow
 26
 27**Environment Setup:**
 28```bash
 29bundle install  # Install Ruby dependencies
 30```
 31
 32**Testing & Quality:**
 33```bash
 34bundle exec rake              # Run full test suite
 35bundle exec rake test         # Alternative test command
 36bundle exec ruby test/test_component.rb -n test_name  # Single test
 37bundle exec rubocop -a        # Auto-fix linting issues
 38bundle exec rake lint         # Check linting
 39bundle exec rake entr         # Watch mode (requires entr tool)
 40```
 41
 42**Running Services:**
 43```bash
 44# Main XMPP gateway
 45./sgx-bwmsgsv2.rb <jid> <password> <host> <port> <app_id> <http_port> <mms_proxy_url>
 46
 47# Redis translator
 48./r2s-bwmsgsv2.rb <redis_queue_suffix> <sgx_hostname> <sgx_https_port>
 49
 50# Background job
 51./bin/notify_inbound_failures_job --webhook-endpoint URL --bw-acct-id ID --bw-password PASS --bw-username USER
 52```
 53
 54## Technical Implementation Details
 55
 56**Async Programming Patterns:**
 57- All async tests use `em :test_name` decorator and must call `EM.stop`
 58- EventMachine promises via `em_promise.rb` for async operations
 59- FakeRedis in tests returns EMPromise objects for consistency
 60
 61**Registration Management:**
 62- `RegistrationRepo` handles JID↔telephone mapping with Redis transactions
 63- Uses `LazyObject` for Redis connection to defer initialization
 64- Implements conflict detection for duplicate telephone registrations
 65- Key patterns: `catapult_cred-{jid}` and `catapult_jid-{tel}`
 66
 67**Error Handling:**
 68- `BandwidthError.for(http_code, body)` parses API error responses
 69- Handles JSON error bodies with field-specific error messages
 70- Falls back to generic error messages for non-JSON responses
 71
 72**Testing Infrastructure:**
 73- FakeRedis class mocks all Redis operations with Promise-based returns
 74- WebMock for HTTP stubbing - always stub external Bandwidth API calls
 75- SimpleCov with branch coverage enabled
 76- Test helper includes pry integration for debugging
 77
 78## Critical Dependencies & Requirements
 79
 80**Required System Components:**
 81- `tai` binary must be present in working directory for high-precision timestamps
 82- Redis server for message queuing and registration storage
 83- EventMachine reactor for async operations
 84
 85**Key Gem Dependencies:**
 86- `blather` (custom fork from develop branch) for XMPP
 87- `em-hiredis` for async Redis operations
 88- `em-http-request` for async HTTP calls
 89- `goliath` for HTTP server capabilities
 90- `sentry-ruby` for error tracking
 91
 92## Configuration & Environment
 93
 94**Environment Variables:**
 95- `ENV` - General environment configuration
 96- `MMS_PATH` - MMS file storage path
 97- `MMS_URL` - MMS proxy URL for media handling
 98
 99**Security Practices:**
100- Never commit credentials, API keys, or phone numbers
101- All sensitive data passed via CLI arguments or environment variables
102- Redis transactions used for atomic registration updates
103- External HTTP calls must be stubbed in tests