README v0.1.5

Documentation for README_v0.1.5 from the Foundation repository.

Foundation

A comprehensive Elixir infrastructure and observability library providing essential services for building robust, scalable applications.

🚀 Overview

Foundation is a standalone library extracted from the ElixirScope project, designed to provide core infrastructure services including configuration management, event storage, telemetry, process management, and fault tolerance patterns.

✨ Key Features

🔧 Configuration Management

Dynamic configuration updates with subscriber notifications
Nested configuration structures with validation
Environment-specific configurations
Runtime configuration changes with rollback support
Path-based configuration access and updates

📊 Event System

Structured event creation and storage
Event querying and correlation tracking
Batch operations for high-throughput scenarios
Event relationships and workflow tracking
In-memory event store with pruning capabilities

📈 Telemetry & Monitoring

Metrics collection (counters, gauges, histograms)
Event measurement and timing
Integration with :telemetry ecosystem
Custom metric handlers and aggregation
Performance monitoring and VM metrics

🛡️ Infrastructure Protection

Circuit breaker patterns (via :fuse)
Rate limiting (via :hammer)
Connection pool management (via :poolboy)
Fault tolerance and resilience patterns
Unified protection facade for coordinated safeguards

🔍 Service Discovery

Service registration and lookup
Health checking for registered services
Process registry with supervision
Namespace-based service organization
Registry performance monitoring

🚨 Error Handling

Structured error types with context
Error context tracking (user, request, operation)
Error aggregation and reporting
Comprehensive error logging
Retry strategies and error recovery

🛠️ Utilities

ID generation and correlation tracking
Time measurement and formatting
Memory usage tracking
System statistics collection

📦 Installation

Add Foundation to your mix.exs:

def deps do
  [
    {:foundation, "~> 0.1.0"}
  ]
end

Ensure Foundation starts before your application:

def application do
  [
    mod: {MyApp.Application, []},
    extra_applications: [:foundation]
  ]
end

🏁 Quick Start

Basic Usage

# Initialize Foundation (typically done by your application supervisor)
:ok = Foundation.initialize()

# Configure your application
:ok = Foundation.Config.update([:app, :feature_flags, :new_ui], true)

# Create and store events
correlation_id = Foundation.Utils.generate_correlation_id()
{:ok, event} = Foundation.Events.new_event(
  :user_action, 
  %{action: "login", user_id: 123},
  correlation_id: correlation_id
)
{:ok, event_id} = Foundation.Events.store(event)

# Emit telemetry metrics
:ok = Foundation.Telemetry.emit_counter(
  [:myapp, :user, :login_attempts], 
  %{user_id: 123}
)

# Use infrastructure protection
result = Foundation.Infrastructure.execute_protected(
  :external_api_call,
  [circuit_breaker: :api_fuse, rate_limiter: {:api_user_rate, "user_123"}],
  fn -> ExternalAPI.call() end
)

Configuration Management

# Get configuration
{:ok, config} = Foundation.Config.get()
{:ok, value} = Foundation.Config.get([:ai, :provider])

# Update configuration
:ok = Foundation.Config.update([:dev, :debug_mode], true)

# Subscribe to configuration changes
:ok = Foundation.Config.subscribe()
# Receive: {:config_notification, {:config_updated, path, new_value}}

# Check updatable paths
{:ok, paths} = Foundation.Config.updatable_paths()

Event Management

# Create different types of events
{:ok, user_event} = Foundation.Events.new_user_event(123, :profile_updated, %{field: "email"})
{:ok, system_event} = Foundation.Events.new_system_event(:maintenance_started, %{duration: "2h"})
{:ok, error_event} = Foundation.Events.new_error_event(:api_timeout, %{service: "users"})

# Store events
{:ok, event_id} = Foundation.Events.store(user_event)

# Query events
{:ok, events} = Foundation.Events.query(%{event_type: :user_action})
{:ok, correlated} = Foundation.Events.get_by_correlation(correlation_id)

Telemetry & Monitoring

# Measure function execution
result = Foundation.Telemetry.measure(
  [:myapp, :database, :query],
  %{table: "users"},
  fn -> Database.fetch_users() end
)

# Emit different metric types
:ok = Foundation.Telemetry.emit_counter([:api, :requests], %{endpoint: "/users"})
:ok = Foundation.Telemetry.emit_gauge([:system, :memory], 1024, %{unit: :mb})

# Get collected metrics
{:ok, metrics} = Foundation.Telemetry.get_metrics()

Infrastructure Protection

# Configure protection for a service
Foundation.Infrastructure.configure_protection(:payment_service, %{
  circuit_breaker: %{
    failure_threshold: 5,
    recovery_time: 30_000
  },
  rate_limiter: %{
    scale: 60_000,  # 1 minute
    limit: 100      # 100 requests per minute
  }
})

# Execute protected operations
result = Foundation.Infrastructure.execute_protected(
  :payment_service,
  [circuit_breaker: :payment_breaker, rate_limiter: {:payment_api, user_id}],
  fn -> PaymentAPI.charge(amount) end
)

🏗️ Architecture

Foundation follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────┐
│             Public API Layer            │
│   Foundation.{Config,Events,Telemetry}  │
├─────────────────────────────────────────┤
│           Business Logic Layer          │
│    Foundation.Logic.{Config,Event}      │
├─────────────────────────────────────────┤
│            Service Layer                │
│ Foundation.Services.{ConfigServer,      │
│   EventStore,TelemetryService}          │
├─────────────────────────────────────────┤
│         Infrastructure Layer            │
│ Foundation.{ProcessRegistry,            │
│   ServiceRegistry,Infrastructure}       │
└─────────────────────────────────────────┘

Key Design Principles

Separation of Concerns: Each layer has a specific responsibility
Contract-Based: All services implement well-defined behaviors
Fault Tolerance: Built-in error handling and recovery mechanisms
Observability: Comprehensive telemetry and monitoring
Testability: Extensive test coverage with different test types

📚 Documentation

Complete API Documentation - Comprehensive API reference
Architecture - Foundation Architecture

🧪 Testing

Foundation includes comprehensive test coverage:

# Run all tests
mix test

# Run specific test suites
mix test.unit          # Unit tests
mix test.integration   # Integration tests
mix test.contract      # Contract tests
mix test.smoke         # Smoke tests

# Run with coverage
mix coveralls
mix coveralls.html     # Generate HTML coverage report

Test Categories

Unit Tests: Test individual modules in isolation
Integration Tests: Test service interactions
Contract Tests: Verify API contracts and behaviors
Smoke Tests: Basic functionality verification
Property Tests: Property-based testing with StreamData

🔧 Development

Setup

# Get dependencies
mix deps.get

# Compile project
mix compile

# Setup development environment
mix setup

# Run development checks
mix dev.check

Quality Assurance

# Format code
mix format

# Run static analysis
mix credo --strict
mix dialyzer

# Run full QA pipeline
mix qa.all

Development Workflow

# Watch tests during development
mix test.watch

# Run development workflow
mix dev.workflow

# Validate architecture
mix validate_architecture

📊 Performance

Foundation is designed for high performance:

Event Storage: In-memory store with configurable retention
Configuration: Cached configuration with efficient updates
Telemetry: Low-overhead metric collection
Circuit Breakers: Fast failure detection
Rate Limiting: Efficient token bucket implementation

Benchmarks

# Run performance benchmarks
mix dev.benchmark

🔒 Security

Input validation at all boundaries
Secure configuration defaults
Access control for sensitive operations
Audit logging for security events
Protection against common vulnerabilities

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the full test suite
Submit a pull request

Code Style

Follow Elixir community conventions
Use mix format for consistent formatting
Add comprehensive documentation
Include typespecs for all public functions

📋 Requirements

Elixir: ~> 1.15
Erlang: Compatible with Elixir requirements
Dependencies: See mix.exs for complete list

Core Dependencies

telemetry - Telemetry events and metrics
jason - JSON encoding/decoding
poolboy - Connection pooling
hammer - Rate limiting
fuse - Circuit breakers

📄 License

See LICENSE file for details.

🆘 Support

Issues: Report bugs and request features on GitHub
Documentation: Comprehensive API documentation available
Community: Join the Elixir community discussions

Foundation - Building reliable Elixir applications from the ground up. 🏗️