APEX Framework

Advanced Production-ready Elixir eXtensions

A comprehensive framework for building robust OTP applications with advanced monitoring, testing, and web interface capabilities.

🚀 Features

• 🎯 MetaProgramming Framework: Automatically generate REST APIs from OTP operations
• 🏗️ Isolated Sandbox Management: Hot-reload capabilities with version management
• 🧪 Distributed Testing: Comprehensive cluster testing with automatic provisioning
• 🌐 Phoenix Integration: Seamless web interface with Plug adapters
• 📊 Advanced UI Components: Real-time monitoring dashboards with terminal aesthetics
• 🔧 Modular Architecture: Use individual packages or the complete framework

📦 Package Overview

APEX consists of five focused packages that can be used independently or together:

Package	Description	Use Case
Arsenal	Metaprogramming framework for automatic REST API generation	Transform OTP operations into HTTP endpoints
Sandbox	Isolated OTP application management with hot-reload	Development and testing with live code updates
ClusterTest	Distributed test cluster management via Mix tasks	Integration testing across multiple nodes
ArsenalPlug	Phoenix/Plug adapter for exposing Arsenal operations	Web framework integration
ApexUI	Advanced web UI components with real-time monitoring	Production dashboards and visualizations

⚡ Quick Start

Install the Complete Framework

def deps do
  [
    {:apex, "~> 0.0.1"}
  ]
end

Or Install Individual Packages

def deps do
  [
    {:arsenal, "~> 0.0.1"},        # Core operations framework
    {:arsenal_plug, "~> 0.0.1"},   # Phoenix integration  
    {:apex_ui, "~> 0.0.1"},             # Web UI components
    {:cluster_test, "~> 0.0.1"},   # Distributed testing
    {:sandbox, "~> 0.0.1"}         # Hot-reload capabilities
  ]
end

Start the Framework

# Start all available APEX packages
{:ok, services} = Apex.start()

# Check what's available
Apex.info()
# => %{
#   apex_version: "0.0.1",
#   packages: [...],
#   available_count: 5
# }

🛠️ Usage Examples

1. Arsenal Operations (Auto-Generated APIs)

# Define an operation
defmodule MyApp.Operations.GetUser do
  @behaviour Arsenal.Operation

  def rest_config do
    %{
      method: :get,
      path: "/api/v1/users/:id",
      summary: "Get user information",
      parameters: [
        %{name: "id", location: "path", type: "string", required: true}
      ]
    }
  end

  def validate_params(params) do
    case params["id"] do
      id when is_binary(id) -> {:ok, %{id: id}}
      _ -> {:error, "Invalid user ID"}
    end
  end

  def execute(%{id: id}) do
    case MyApp.Users.get_user(id) do
      nil -> {:error, :user_not_found}
      user -> {:ok, user}
    end
  end

  def format_response(user) do
    %{data: %{id: user.id, name: user.name, email: user.email}}
  end
end

# Register and expose via HTTP
Apex.start_arsenal()
Apex.register_operation(MyApp.Operations.GetUser)
# Now available at: GET /api/v1/users/123

2. Phoenix Integration

# In your router
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # Arsenal API routes
  pipeline :arsenal do
    plug :accepts, ["json"]
    plug ArsenalPlug
  end

  scope "/api/v1", MyAppWeb do
    pipe_through [:api, :arsenal]
    
    # Documentation endpoints
    get "/arsenal/docs", ArsenalPlug.ArsenalController, :docs
    get "/arsenal/operations", ArsenalPlug.ArsenalController, :list_operations
    
    # Catch-all for Arsenal operations
    match :*, "/*path", ArsenalPlug.ArsenalController, :operation_handler
  end
end

3. Real-time UI Dashboard

defmodule MyAppWeb.DashboardLive do
  use MyAppWeb, :live_view

  def render(assigns) do
    ~H"""
    <div class="grid grid-cols-2 gap-4 p-4">
      <.live_component 
        module={ApexUI.Components.Widgets.ChartWidget}
        id="system-metrics"
        chart_type={:line}
        data={@metrics_data}
        title="System Performance"
        real_time={true}
        height={400}
      />
      
      <.live_component 
        module={ApexUI.Components.Widgets.ChartWidget}
        id="process-distribution"
        chart_type={:pie}
        data={@process_data}
        title="Process Distribution"
        color_scheme={:multi}
      />
    </div>
    """
  end

  def mount(_params, _session, socket) do
    if connected?(socket) do
      :timer.send_interval(1000, self(), :update_metrics)
    end

    {:ok, assign(socket, metrics_data: [], process_data: [])}
  end
end

4. Distributed Testing

# Start a test cluster
mix cluster_test start --size 3

# Run distributed tests
mix cluster_test run MyApp.DistributedTest

# Check cluster status
mix cluster_test status

# Stop cluster
mix cluster_test stop

5. Sandbox Development

# Create an isolated sandbox
{:ok, sandbox} = Apex.create_sandbox(:my_sandbox, MyApp)

# Hot-reload code without restarting
new_beam = File.read!("path/to/updated_module.beam")
Apex.hot_reload_sandbox(:my_sandbox, new_beam)

# Test in isolation
result = Sandbox.call_in_sandbox(:my_sandbox, MyModule, :my_function, [args])

🔧 Configuration

Configure APEX in your config/config.exs:

config :apex,
  # Arsenal configuration
  arsenal: [
    auto_register: true,
    openapi_version: "3.0.0"
  ],
  # UI configuration  
  ui: [
    theme: :terminal_green,
    real_time_updates: true,
    chart_defaults: %{
      height: 300,
      animated: true,
      color_scheme: :green
    }
  ],
  # Cluster test configuration
  cluster_test: [
    default_cluster_size: 3,
    startup_timeout: 30_000
  ],
  # Sandbox configuration
  sandbox: [
    hot_reload: true,
    version_management: true
  ]

🏗️ Architecture

APEX follows a modular architecture where each package focuses on a specific concern:

APEX Framework
├── 🎯 Arsenal (Core operations & metaprogramming)
│   ├── Operation behavior definition
│   ├── Registry for operation management
│   └── Automatic API documentation
├── 🌐 ArsenalPlug (Phoenix/HTTP integration)
│   ├── Dynamic request routing
│   ├── Parameter validation & merging
│   └── Error handling with proper HTTP codes
├── 📊 ApexUI (Web interface & visualizations)  
│   ├── LiveView components & widgets
│   ├── Real-time charts & dashboards
│   └── Terminal-themed UI system
├── 🧪 ClusterTest (Distributed testing)
│   ├── Automated cluster provisioning
│   ├── Health monitoring & diagnostics
│   └── Mix task integration
└── 🏗️ Sandbox (Hot-reload & isolation)
    ├── Isolated OTP application management
    ├── Module version management
    └── Hot-reload capabilities

📚 Documentation

Package Documentation

• Arsenal README - Core operations framework
• Sandbox README - Isolated application management
• ClusterTest README - Distributed testing
• ArsenalPlug README - Phoenix integration
• ApexUI README - Advanced web UI components

API Documentation

Generate comprehensive API docs:

mix docs

Online Documentation

• APEX Framework Documentation
• Getting Started Guide
• Architecture Overview

🧪 Testing

Run the complete test suite:

# Run all tests
mix test

# Run with coverage
mix test --cover

# Run distributed tests
mix cluster_test run

Test individual packages:

cd arsenal && mix test
cd sandbox && mix test
cd cluster_test && mix test
cd arsenal_plug && mix test
cd apex_ui && mix test

🚀 Production Usage

Performance Considerations

1. Memory Management: Use max_data_points in UI components to prevent memory growth
2. Operation Registry: Limit auto-registration in production for security
3. Cluster Testing: Use dedicated test environments for distributed testing
4. Sandbox Usage: Prefer sandbox for development/staging, not production hot-reload

Security Best Practices

1. Arsenal Operations: Validate all inputs and implement proper authorization
2. Web Interface: Use authentication middleware for sensitive operations
3. Cluster Testing: Isolate test clusters from production networks
4. Sandbox Management: Restrict sandbox creation in production environments

Monitoring Integration

# Telemetry integration
:telemetry.attach_many(
  "apex-metrics",
  [
    [:apex, :arsenal, :operation, :execute, :stop],
    [:apex, :sandbox, :hot_reload, :stop],
    [:apex, :cluster_test, :start, :stop]
  ],
  &MyApp.MetricsHandler.handle_event/4,
  []
)

🔧 Development

Local Development Setup

# Clone the repository
git clone https://github.com/apex-framework/apex.git
cd apex

# Install dependencies for all packages
mix deps.get

# Run tests
mix test

# Start development server
mix phx.server

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (mix test)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow Elixir style guide and use mix format
• Add comprehensive documentation for new features
• Include tests for all new functionality
• Update relevant README files
• Ensure backward compatibility

🤝 Community

• GitHub: apex-framework
• Issues: Bug Reports & Feature Requests
• Discussions: GitHub Discussions
• Discord: APEX Community

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Built with ❤️ using Elixir and Phoenix
• Inspired by OTP design principles and production-ready patterns
• Special thanks to the Elixir community for feedback and contributions

---

APEX Framework - Elevating your Elixir applications to production excellence.