ERPax

Appearance

For Developers ​

ERPax is built with developers in mind. Clean architecture, comprehensive APIs, and extensive documentation. New to ERPax? Start with the Platform Overview for a comprehensive introduction to ERPax's architecture, features, and design principles.

Technical Overview ​

Technology Stack ​

ERPax is built as a modern SaaS platform with:

  • API: RESTful JSON API with 337+ endpoints
  • Authentication: Session-based and token-based authentication
  • Authorization: Role-based access control (RBAC)
  • Accounting: Automatic double-entry accounting system
  • Multi-Tenancy: Automatic tenant isolation via API
  • Caching: HTTP caching (ETags, Last-Modified, Cache-Control)
  • Frontend: JavaScript/Stimulus for interactive UI
  • Integration: Webhook support and external system integration

See Platform Overview for detailed information about API features and capabilities.

Architecture Highlights ​

Unified Document Model ​

The core innovation: one Invoice model handles all document types (invoices, purchase orders, quotations, credit notes, etc.) through the invoice_type field and 42 concerns. Benefits:

  • Single API for all document types
  • Consistent data model
  • Shared business logic
  • Easier to extend and maintain

Concern-Based Architecture ​

Business logic organized into concerns:

  • Invoice model: 42 concerns
  • Modular, testable, reusable
  • Clear separation of concerns
  • Easy to extend

Multi-Tenant by Design ​

ERPax is multi-tenant from the ground up:

  • Automatic data isolation per tenant
  • Tenant context managed automatically via API
  • Hierarchical domain support
  • Complete data isolation - no cross-tenant access

Automatic Workflows ​

Lifecycle concerns handle automatic transitions:

  • TYPE_HANDLERS for type-specific behavior
  • GROUP_HANDLERS for group-based behavior
  • Automatic number generation
  • Automatic account assignment

Key Technical Features ​

API & Integration ​

RESTful JSON API

  • Standard REST endpoints (337+ documented)
  • JSON responses with consistent format
  • Advanced filtering via query parameters
  • Pagination support
  • Batch operations External Integrations
  • Shopify product sync
  • E-commerce platform integration
  • Payment gateway integration
  • Webhook support (see Integration Guide)

Data Model ​

API Data Structure

  • Unified Invoice model for all documents (via invoice_type field)
  • Normalized accounting structure accessible via API
  • Hierarchical domain model with automatic tenant scoping
  • Flexible address/party model for business relationships API Features
  • JSON/JSONB metadata support
  • Full-text search via API endpoints
  • Automatic data validation
  • Consistent response formats

Security ​

Authentication & Authorization

  • Session-based and token-based authentication
  • Role-based access control (RBAC) via API
  • Namespace-based permissions (admin, sales, client, system)
  • Resource-level permissions enforced automatically Multi-Tenant Security
  • Automatic data scoping per tenant
  • Complete tenant isolation via API
  • Cross-tenant access prevention
  • Complete audit trail accessible via API

Performance ​

Caching Strategy

  • HTTP caching (ETags, Last-Modified, Cache-Control)
  • Browser caching for static assets
  • Service worker caching for offline support
  • API response caching with appropriate headers Optimizations
  • Efficient API responses with pagination
  • Automatic query optimization
  • Indexed database fields
  • Efficient aggregations via API

Frontend Development ​

Stimulus for DRY Frontend

  • Reusable controllers eliminate code duplication
  • Declarative HTML with data attributes
  • No inline JavaScript needed
  • Consistent behavior across the application Benefits:
  • Write once, use many times
  • Maintainable and testable
  • Works with Turbo for SPA-like behavior
  • Complements the admin interface

See Frontend Development Guide for complete frontend development patterns and examples.

Getting Started ​

See the Getting Started Guide for API integration setup, authentication, and first API calls.

Development Workflow ​

Testing

  • Rails 8.1 native transactional tests
  • Model tests with concerns
  • Controller tests with multi-tenancy
  • Integration tests Code Quality
  • RuboCop for style
  • Concern-based organization
  • DRY principles
  • Documentation inline

Architecture Documentation ​

See Platform Overview for comprehensive architecture documentation including:

  • Multi-tenant architecture and data isolation
  • Authorization system and permissions
  • Request processing flow
  • Caching strategies
  • Design principles and architectural decisions

Data Models ​

See API endpoint documentation for complete data structure information:

API Documentation ​

REST API ​

Namespaces

  • /admin/ - Full administrative access
  • /sales/ - Sales-focused access
  • /client/ - Customer self-service
  • /system/ - System administration Standard Operations
  • GET - List resources (with filtering, pagination)
  • GET /:id - Show resource
  • POST - Create resource
  • PATCH/PUT - Update resource
  • DELETE - Delete resource Filtering
  • Ransack-based filtering
  • Text search
  • Date ranges
  • Multi-select filters Batch Actions
  • Update multiple records
  • Bulk operations
  • Confirmation dialogs

Example API Usage ​

List Invoices

bash
GET /admin/invoices.json
GET /admin/invoices.json?q[invoice_type_eq]=invoice
GET /admin/invoices.json?q[date_gteq]=2024-01-01

Create Invoice

bash
POST /admin/invoices.json
{
  "invoice": {
    "invoice_type": "invoice",
    "seller_id": 1,
    "buyer_id": 2,
    "date": "2024-01-15",
    "currency_code": "USD"
  }
}

Update Invoice

bash
PATCH /admin/invoices/123.json
{
  "invoice": {
    "confirmed": true
  }
}

Integration Guide ​

Shopify Integration ​

Sync products from Shopify via API:

bash
POST /admin/items.json
{
  "item": {
    "shopify_product_id": "123456",
    "name": "Product Name",
    "sku": "SKU-001",
    "price_cents": 10000
  }
}

See Platform Overview for integration patterns and API Reference for complete API documentation.

Payment Gateway Integration ​

Record payments via API:

bash
POST /admin/payments.json
{
  "payment": {
    "invoice_id": 123,
    "amount_cents": 10000,
    "payment_method": "Credit Card",
    "received_at": "2025-01-15T10:00:00Z"
  }
}

See Payments API for complete payment workflow documentation.

Webhook Integration ​

Webhook support is planned for future releases. When available, webhooks will support:

  • Invoice confirmed events
  • Payment received events
  • Accounting equation created events See Platform Overview for integration patterns and webhook support.

Gem Stack Overview ​

ERPax uses carefully selected gems that enable its capabilities. Understanding the gem stack helps you extend and customize ERPax effectively.

Core Gems by Category ​

API Features

  • RESTful JSON API with 337+ endpoints
  • Version history accessible via API
  • Hierarchical data structures via API
  • Full-text search via API endpoints
  • Multi-currency support with formatted amounts
  • PDF generation and file processing
  • QR code generation for documents Frontend Development
  • JavaScript/Stimulus for interactive UI
  • Reusable Stimulus controllers
  • API client patterns
  • Webhook integration Performance
  • HTTP caching with ETags and Cache-Control
  • Efficient API responses with pagination
  • Optimized JSON responses See Platform Overview for detailed information about API features and capabilities.

How API Features Work ​

ERPax provides comprehensive API features:

Versioning & Auditing ​

Version History API provides complete audit trails:

  • Every resource change is tracked
  • Accessible via /admin/{resource}/{id}/versions.json
  • Multi-tenant version scoping
  • Compliance support

Hierarchical Data ​

Tree Structures via API:

  • Address parent-child relationships accessible via API
  • Efficient tree queries with ?include=children
  • Organizational structures

Financial Management ​

Multi-Currency API features:

  • Currency codes in all monetary fields
  • Formatted amounts for display
  • Real-time exchange rates
  • Accurate financial calculations

Authorization ​

Role-Based Access Control via API:

  • Automatic permission checking on all requests
  • Role-based permissions
  • Namespace-based access
  • Resource-level control

Full-Text Search ​

Search API features:

  • Page content search via API
  • Multi-column search
  • Ranked results
  • No external dependencies needed See Platform Overview for detailed API integration patterns and API Reference for complete API documentation.

Integration Patterns ​

ERPax uses a modular architecture that allows for extensions and customizations. The system is designed with clear extension points for integrating external services and customizing behavior. See Gem Integration Architecture for detailed integration patterns and API Reference for API-based integration options.

Extension Points ​

ERPax provides several extension points for customization:

API-Based Extensions ​

  • Custom API Endpoints - Extend functionality via REST API
  • Webhook Integration - Connect to external systems via webhooks
  • Custom Workflows - Implement custom business logic via API

Frontend Extensions ​

  • Stimulus Controllers - Add custom UI behavior
  • Admin Interface Customization - Customize admin interface via Pages system
  • Custom Views - Create custom views using the Pages system See API Reference for available endpoints and Frontend Development Guide for frontend customization.

Best Practices ​

Multi-Tenancy ​

  • All API requests are automatically scoped to current tenant
  • Tenant context is set automatically based on request hostname
  • No manual tenant scoping needed - handled by API
  • Use unscoped only for system-level operations

Concerns ​

  • Keep concerns focused and single-purpose
  • Use concerns for reusable logic
  • Document concern dependencies
  • Test concerns independently

Performance ​

  • Use eager loading for associations
  • Leverage caching where appropriate
  • Use scoped queries efficiently
  • Monitor query performance

Resources ​

Documentation ​

Examples ​

Ready to build with ERPax? Start with the Platform Overview for a comprehensive introduction, then explore the Getting Started Guide to dive deeper.

Released under an open source license.

Copyright © ERPax.com