onix/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Beckn-ONIX is a middleware adapter system for the Beckn protocol, designed for any Beckn-enabled network. It acts as a bridge between BAP (Beckn Application Platform) and BPP (Beckn Provider Platform) systems, providing a plugin-based architecture for handling HTTP requests, routing, validation, signing, and integration with external services.

Technology Stack

• Language: Go 1.23 (with Go 1.23.4 toolchain)
• Architecture: Plugin-based middleware system
• Key Dependencies:
  • Redis (caching)
  • RabbitMQ (messaging via amqp091-go)
  • HashiCorp Vault (secrets management)
  • JSON Schema validation (jsonschema/v6)
• Containerization: Docker with Dockerfile.adapter
• Frontend: Node.js-based GUI component (onix-gui/)

Build and Development Commands

Build locally

go build -o server cmd/adapter/main.go

Run with configuration

./server --config=config/onix/adapter.yaml

Docker build

docker build -f Dockerfile.adapter -t beckn-onix-adapter .

Run tests

go test ./...

Run specific test

go test ./pkg/plugin/implementation/cache -v

Run tests with coverage

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out  # View coverage in browser
go tool cover -func=coverage.out  # View coverage summary

Run tests with race detection

go test -race ./...

Format and lint code

go fmt ./...
go vet ./...
golangci-lint run  # Requires golangci-lint installation

Clean build artifacts

rm -f server
rm -rf plugins/*.so

Module maintenance

go mod tidy       # Clean up dependencies
go mod download   # Download dependencies
go mod verify     # Verify dependencies

Local Development Setup

For local development without Docker:

1. Build plugins (required for the plugin-based architecture):

./build-plugins.sh

2. Create required directories:

mkdir -p schemas

3. Run with local config:

go run cmd/adapter/main.go --config=config/local-dev.yaml

Note: The application requires:

• Redis running on localhost:6379 for caching
• Plugins built as .so files in the ./plugins directory
• Schema files in ./schemas for validation (optional)
• HashiCorp Vault for key management (optional, can be disabled in config)

Architecture Overview

Core Components

1. cmd/adapter/main.go: Main application entry point that:

   • Loads YAML configuration
   • Initializes plugin manager
   • Sets up HTTP server with configurable timeouts
   • Registers modules and their handlers

2. core/module/: Core business logic and module system

   • module.go: Module registration and management
   • handler/: HTTP request handlers and processing steps
   • client/: Client registry for external service connections

3. pkg/plugin/: Extensible plugin system with:

   • definition/: Plugin interfaces (cache, router, signer, validator, etc.)
   • implementation/: Concrete implementations of each plugin type
   • manager.go: Plugin lifecycle management

Plugin Types

The system supports these plugin types:

• cache: Redis-based caching
• router: Request routing based on YAML configuration
• signer/signvalidator: Request signing and validation
• schemavalidator: JSON schema validation
• keymanager: HashiCorp Vault integration for secrets
• publisher: RabbitMQ message publishing
• encrypter/decrypter: AES encryption/decryption
• reqpreprocessor: Request preprocessing middleware (UUID generation, etc.)

Configuration Structure

The system uses YAML configuration files in config/ directory:

• config/local-dev.yaml: Simplified configuration for local development
• config/local-routing.yaml: Routing rules for local development
• config/onix/: Combined BAP+BPP configuration for production
• config/onix-bap/: BAP-only deployment configuration
• config/onix-bpp/: BPP-only deployment configuration

Each configuration defines:

• HTTP server settings (port, timeouts)
• Plugin manager settings
• Modules with their handlers, plugins, and processing steps

Request Flow

1. HTTP request received by server
2. Routed to appropriate module (bapTxnReceiver, bapTxnCaller, bppTxnReceiver, bppTxnCaller)
3. Processed through configured steps (validateSign, addRoute, validateSchema, sign)
4. Each step uses configured plugins to perform its function
5. Response returned or forwarded based on routing configuration

Module Types and Responsibilities

• bapTxnReceiver: Receives incoming requests at BAP (buyer platform)
• bapTxnCaller: Makes outgoing calls from BAP to BPP
• bppTxnReceiver: Receives incoming requests at BPP (provider platform)
• bppTxnCaller: Makes outgoing calls from BPP to BAP

Module Configuration Patterns

Modules follow this structure:

• name: Module identifier
• path: HTTP endpoint path
• handler: Processing configuration including:
  • role: "bap" or "bpp"
  • plugins: Plugin instances with their configurations
  • steps: Ordered list of processing steps

Processing Steps

Available processing steps that can be configured:

• validateSign: Validates digital signatures on incoming requests
• addRoute: Determines routing based on configuration
• validateSchema: Validates against JSON schemas
• sign: Signs outgoing requests
• cache: Caches requests/responses
• publish: Publishes messages to queue

Environment Variables

The configuration supports environment variable substitution using ${variable} syntax, commonly used for:

• ${projectID}: GCP project ID for Vault and Pub/Sub
• Connection strings and service endpoints

Testing

Tests are colocated with source files using _test.go suffix. Each plugin implementation has comprehensive test coverage including mock data in testdata/ directories.

CI/CD Pipeline

The project uses GitHub Actions for CI with the following checks:

• Unit tests with minimum 90% coverage requirement
• golangci-lint for code quality
• Coverage reports uploaded to Codecov