AGENTS.md

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

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

bundle exec rake lint         # Run RuboCop linter
bundle exec rubocop          # Direct RuboCop invocation

Development Workflow

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

Database Setup

cd schemas
sqitch deploy                # Deploy database migrations
sqitch revert                # Revert migrations

Configuration

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

Running the Application

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