# AGENTS.md

This file provides guidance to LLM-based agents when working with code in this repository.

## Project Overview

This is a Ruby-based XMPP/telecommunications service (SGX JMP) that handles VoIP services, SIM management, payment processing, and Snikket XMPP server provisioning. It's built with EventMachine for async I/O, Roda for web interfaces, and integrates with Bandwidth, Braintree, and various crypto payment systems.

## Architecture

- **Entry Points**: `sgx_jmp.rb` (main XMPP component) and `web.rb` (HTTP interface)
- **Core Libraries**: Located in `lib/` directory containing domain objects, repositories, and business logic
- **Forms**: UI forms in `forms/` directory using a custom form system
- **Database**: PostgreSQL with Sqitch migrations in `schemas/`
- **Configuration**: Dhall-based config system (`config.dhall`, typed by `config-schema.dhall`)
- **Tests**: Minitest-based tests in `test/` directory

## Development Commands

### Testing
```bash
bundle exec rake test          # Run all tests
bundle exec rake              # Default task (runs tests)
bundle exec ruby test/test_specific.rb  # Run specific test file
```

### Linting
```bash
bundle exec rake lint         # Run RuboCop linter
bundle exec rubocop          # Direct RuboCop invocation
```

### Development Workflow
```bash
bundle install --path=.gems  # Install dependencies locally
bundle exec rake entr        # Auto-run tests and linting on file changes
```

### Database Setup
```bash
cd schemas
sqitch deploy                # Deploy database migrations
sqitch revert                # Revert migrations
```

### Configuration
```bash
cp config.dhall.sample config.dhall
# Edit config.dhall for local development
make config-schema.dhall     # Generate config schema
```

### Running the Application
```bash
bundle exec ruby sgx_jmp.rb ./config.dhall    # Start main XMPP component
bundle exec ruby web.rb ./config.dhall        # Start web interface
```

## Key Components

- **Customer Management**: `Customer`, `CustomerRepo`, billing and plan management
- **VoIP Integration**: Bandwidth SDK integration, call routing, CDR processing
- **Payment Processing**: Braintree, crypto (BTC/BCH), PayPal integration
- **SIM Management**: Physical and eSIM provisioning, inventory tracking
- **Snikket Integration**: XMPP server provisioning and management
- **Number Porting**: LNP (Local Number Portability) workflows

## Database

Uses PostgreSQL with Sqitch for schema management. Key tables include customers, transactions, plans, CDR (call detail records), and SIM inventory. Database migrations are in `schemas/deploy/`.

## Development Notes

- Uses EventMachine for async I/O - wrap blocking operations in `EM.defer`
- Dhall configuration provides type safety for config files
- Custom form system in `forms/` with Slim templates
- Repository pattern for data access
- Value objects with `value_semantics` gem
- Redis for caching and real-time data