docs: Add Elixir SDK README with comprehensive API documentation and implement modular architecture with GenServer support

- Add README.md with installation instructions, architecture overview, and API examples for all SDK modules
- Refactor TelecomSDK main module to use modular API clients (SubscribersAPI, UsageAPI, PaymentAPI, RatingPlanAPI, SystemAPI, GraphQLAPI)
- Add AuthProvider class with API key and JWT token support (generate_jwt_token, validate_jwt_token methods)
- Add HTTPClient base

sdk/elixir/README.md

@@ -0,0 +1,257 @@
+# Telecom Platform Elixir SDK
+
+Elixir SDK for the Telecom Platform with GenServer-based async access and full pattern matching.
+
+## Features
+
+- **Modular Architecture**: Separate modules for authentication, HTTP client, and API services
+- **GenServer Support**: Full GenServer-based async access
+- **Pattern Matching**: Full Elixir pattern matching
+- **Type Safety**: Struct-based data structures with typespecs
+- **Error Handling**: Comprehensive error handling
+- **Retry Logic**: Built-in retry mechanism with exponential backoff
+- **OTP Integration**: Full OTP application support
+
+## Installation
+
+Add to your `mix.exs`:
+
+```elixir
+defp deps do
+  [
+    {:telecom_sdk, path: "../sdk/elixir"}
+  ]
+end
+```
+
+Or install from source:
+
+```bash
+cd sdk/elixir
+mix deps.get
+mix compile
+```
+
+## Architecture
+
+The SDK is organized into modular components:
+
+- `auth.ex` - Authentication provider handling API keys and JWT tokens
+- `http_client.ex` - HTTP client with retry logic and authentication
+- `subscribers_api.ex` - Subscriber management API
+- `usage_api.ex` - Usage tracking API
+- `payments_api.ex` - Payment processing API
+- `rating_plans_api.ex` - Rating plan management API
+- `system_api.ex` - System monitoring API
+- `graphql_api.ex` - GraphQL query execution
+- `telecom_sdk.ex` - Main SDK client integrating all modules
+
+## Quick Start
+
+```elixir
+# Start the SDK
+{:ok, _pid} = TelecomSDK.start_link(
+  api_url: "http://localhost:8000",
+  api_key: "your-api-key",
+  enable_logging: true
+)
+
+# Get subscriber
+{:ok, subscriber} = TelecomSDK.get_subscriber(1)
+IO.puts("Subscriber: #{subscriber.first_name} #{subscriber.last_name}")
+
+# List subscribers
+{:ok, list} = TelecomSDK.list_subscribers(1, 50, "active")
+IO.puts("Total subscribers: #{list.total}")
+```
+
+## API Reference
+
+### Configuration
+
+```elixir
+config = %TelecomSDK.Config{
+  api_url: "http://localhost:8000",
+  api_key: "your-api-key",
+  jwt_secret: "your-jwt-secret",
+  timeout: 30_000,
+  max_retries: 3,
+  retry_delay: 1_000,
+  enable_logging: false
+}
+```
+
+### Subscriber Management
+
+```elixir
+# Get subscriber
+{:ok, subscriber} = TelecomSDK.get_subscriber(1)
+
+# List subscribers
+{:ok, list} = TelecomSDK.list_subscribers(1, 50, "active")
+
+# Create subscriber
+{:ok, subscriber} = TelecomSDK.create_subscriber(%{
+  imsi: "208930000000001",
+  msisdn: "+1234567890",
+  first_name: "John",
+  last_name: "Doe",
+  email: "[email protected]",
+  plan_id: 1
+})
+
+# Update subscriber
+{:ok, subscriber} = TelecomSDK.update_subscriber(1, %{
+  first_name: "Jane"
+})
+
+# Delete subscriber
+{:ok, success} = TelecomSDK.delete_subscriber(1)
+
+# Suspend subscriber
+{:ok, subscriber} = TelecomSDK.suspend_subscriber(1)
+
+# Activate subscriber
+{:ok, subscriber} = TelecomSDK.activate_subscriber(1)
+```
+
+### Usage Management
+
+```elixir
+# Get usage stats
+start_date = DateTime.add(DateTime.utc_now(), -30, :day)
+end_date = DateTime.utc_now()
+{:ok, stats} = TelecomSDK.get_usage_stats(1, start_date, end_date)
+
+# List usage events
+{:ok, events} = TelecomSDK.list_usage_events(%{
+  subscriber_id: 1,
+  usage_type: "data",
+  page: 1,
+  page_size: 50
+})
+
+# Get real-time usage
+{:ok, realtime} = TelecomSDK.get_real_time_usage(1)
+```
+
+### Payment Management
+
+```elixir
+# Create payment transaction
+{:ok, transaction} = TelecomSDK.create_payment_transaction(%{
+  subscriber_id: "1",
+  amount: 25.00,
+  currency: "USD",
+  gateway: "stripe",
+  metadata: %{description: "Monthly plan"}
+})
+
+# Get transaction
+{:ok, transaction} = TelecomSDK.get_payment_transaction("txn-123")
+
+# List transactions
+{:ok, transactions} = TelecomSDK.list_payment_transactions(%{
+  subscriber_id: 1,
+  status: "completed",
+  page: 1,
+  page_size: 50
+})
+```
+
+### Rating Plans
+
+```elixir
+# List rating plans
+{:ok, plans} = TelecomSDK.list_rating_plans()
+
+# Get specific plan
+{:ok, plan} = TelecomSDK.get_rating_plan("plan-123")
+```
+
+### System Management
+
+```elixir
+# Get system stats
+{:ok, stats} = TelecomSDK.get_system_stats()
+
+# Get health status
+{:ok, health} = TelecomSDK.get_health_status()
+```
+
+### GraphQL
+
+```elixir
+# Execute GraphQL query
+query = """
+query GetSubscribers($first: Int) {
+  subscribers(first: $first) {
+    id
+    firstName
+    lastName
+  }
+}
+"""
+
+variables = %{first: 10}
+{:ok, result} = TelecomSDK.execute_graphql_query(query, variables)
+```
+
+## Authentication
+
+### JWT Token Generation
+
+```elixir
+# Generate JWT token
+{:ok, token} = TelecomSDK.generate_jwt_token("user-123", 24, %{custom_claim: "value"})
+
+# Validate JWT token
+{:ok, claims} = TelecomSDK.validate_jwt_token(token)
+```
+
+## Error Handling
+
+```elixir
+case TelecomSDK.get_subscriber(1) do
+  {:ok, subscriber} ->
+    IO.puts("Subscriber: #{subscriber.first_name}")
+  {:error, :authentication_error} ->
+    IO.puts("Authentication failed")
+  {:error, :api_error} ->
+    IO.puts("API error")
+  {:error, :network_error} ->
+    IO.puts("Network error")
+  {:error, reason} ->
+    IO.puts("Error: #{inspect(reason)}")
+end
+```
+
+## Development
+
+### Running Tests
+
+```bash
+mix test
+```
+
+### Code Style
+
+```bash
+mix format
+mix compile --warnings-as-errors
+```
+
+### Building
+
+```bash
+mix compile
+```
+
+## Requirements
+
+- Elixir 1.13+
+- OTP 26+
+
+## License
+
+This SDK is licensed under the MIT License.