1# AGENTS.md
 2
 3This file provides guidance to LLM-based agents when working with code in this repository.
 4
 5## Project Overview
 6
 7This 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.
 8
 9## Architecture
10
11- **Entry Points**: `sgx_jmp.rb` (main XMPP component) and `web.rb` (HTTP interface)
12- **Core Libraries**: Located in `lib/` directory containing domain objects, repositories, and business logic
13- **Forms**: UI forms in `forms/` directory using a custom form system
14- **Database**: PostgreSQL with Sqitch migrations in `schemas/`
15- **Configuration**: Dhall-based config system (`config.dhall`, typed by `config-schema.dhall`)
16- **Tests**: Minitest-based tests in `test/` directory
17
18## Development Commands
19
20### Testing
21```bash
22bundle exec rake test          # Run all tests
23bundle exec rake              # Default task (runs tests)
24bundle exec ruby test/test_specific.rb  # Run specific test file
25```
26
27### Linting
28```bash
29bundle exec rake lint         # Run RuboCop linter
30bundle exec rubocop          # Direct RuboCop invocation
31```
32
33### Development Workflow
34```bash
35bundle install --path=.gems  # Install dependencies locally
36bundle exec rake entr        # Auto-run tests and linting on file changes
37```
38
39### Database Setup
40```bash
41cd schemas
42sqitch deploy                # Deploy database migrations
43sqitch revert                # Revert migrations
44```
45
46### Configuration
47```bash
48cp config.dhall.sample config.dhall
49# Edit config.dhall for local development
50make config-schema.dhall     # Generate config schema
51```
52
53### Running the Application
54```bash
55bundle exec ruby sgx_jmp.rb ./config.dhall    # Start main XMPP component
56bundle exec ruby web.rb ./config.dhall        # Start web interface
57```
58
59## Key Components
60
61- **Customer Management**: `Customer`, `CustomerRepo`, billing and plan management
62- **VoIP Integration**: Bandwidth SDK integration, call routing, CDR processing
63- **Payment Processing**: Braintree, crypto (BTC/BCH), PayPal integration
64- **SIM Management**: Physical and eSIM provisioning, inventory tracking
65- **Snikket Integration**: XMPP server provisioning and management
66- **Number Porting**: LNP (Local Number Portability) workflows
67
68## Database
69
70Uses 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/`.
71
72## Development Notes
73
74- Uses EventMachine for async I/O - wrap blocking operations in `EM.defer`
75- Dhall configuration provides type safety for config files
76- Custom form system in `forms/` with Slim templates
77- Repository pattern for data access
78- Value objects with `value_semantics` gem
79- Redis for caching and real-time data