Home

AlexaVoxCraft is a modular C# .NET library for building Amazon Alexa skills using modern .NET practices. It provides comprehensive support for Alexa skill development with CQRS patterns, visual interfaces, and AWS Lambda hosting.

Key Features¶

• 🎯 MediatR Integration: CQRS-style request handling with pipeline behaviors and auto-discovery
• 🎨 APL Support: Complete Alexa Presentation Language implementation for rich visual interfaces
• ⚡ Lambda Hosting: Optimized AWS Lambda runtime with custom serialization and ReadyToRun publishing
• 📊 Session Management: Robust session attribute handling and game state persistence
• 🔧 Pipeline Behaviors: Request/response interceptors for cross-cutting concerns like logging and validation
• 🧪 Testing Support: Comprehensive testing utilities with AutoFixture integration and property-based testing

Installation¶

# Core MediatR integration and Lambda hosting
dotnet add package AlexaVoxCraft.MediatR.Lambda

# APL visual interface support
dotnet add package AlexaVoxCraft.Model.Apl

# Structured logging for Alexa skills
dotnet add package AlexaVoxCraft.Logging

Quick Start - Building a Trivia Skill¶

All code examples in this documentation demonstrate building a trivia game skill. Here's a complete implementation:

// Program.cs
using AlexaVoxCraft.MediatR.Lambda;
using AlexaVoxCraft.Model.Apl;
using AlexaVoxCraft.Model.Response;

APLSupport.Add();

return await LambdaHostExtensions.RunAlexaSkill<TriviaSkillFunction, APLSkillRequest, SkillResponse>();

// Function class
public class TriviaSkillFunction : AlexaSkillFunction<APLSkillRequest, SkillResponse>
{
    protected override void Init(IHostBuilder builder)
    {
        builder
            .UseHandler<LambdaHandler, APLSkillRequest, SkillResponse>()
            .ConfigureServices((context, services) =>
            {
                // Register all handlers and services from assembly
                services.AddSkillMediator(context.Configuration, cfg => 
                    cfg.RegisterServicesFromAssemblyContaining<TriviaSkillFunction>());

                // Add your business services
                services.AddScoped<IGameService, GameService>();
                services.AddScoped<IQuestionRepository, QuestionRepository>();
            });
    }
}

// Request Handler
public class LaunchRequestHandler : IRequestHandler<LaunchRequest>
{
    public bool CanHandle(IHandlerInput handlerInput) => 
        handlerInput.RequestEnvelope.Request is LaunchRequest;

    public async Task<SkillResponse> Handle(IHandlerInput input, CancellationToken cancellationToken)
    {
        return await input.ResponseBuilder
            .Speak("Welcome to Trivia Challenge! Ready to test your knowledge?")
            .Reprompt("Say yes to start playing, or help for instructions.")
            .WithSimpleCard("Trivia Challenge", "Welcome to Trivia Challenge!")
            .GetResponse(cancellationToken);
    }
}

Available Components¶

📝 Note: All component documentation uses trivia skill examples to demonstrate features and patterns.

Request Handling¶

Modern request handling patterns with trivia game examples:

• MediatR integration for CQRS
• Auto-discovery of handlers and services
• Type-safe request/response processing
• Exception handling pipeline
• Request validation and routing

APL Integration¶

Rich visual interface support for trivia questions with:

• Fluent document builder API
• Multi-slide presentations
• Interactive components
• Voice/touch synchronization
• Custom layout management

Lambda Hosting¶

Optimized AWS Lambda runtime for trivia skills with:

• Custom serialization for Alexa models
• ReadyToRun publishing for faster cold starts
• Self-contained deployment options
• Environment-specific configuration
• Comprehensive logging integration

Session Management¶

Robust game state management with:

• Session attribute persistence
• Game state tracking
• User data management
• Multi-turn conversation support
• DynamoDB integration patterns

Pipeline Behaviors¶

Cross-cutting concerns for skill management with:

• Request/response interceptors
• Logging and telemetry
• User authentication and authorization
• Error handling and recovery
• Performance monitoring

Documentation¶

• Examples - Complete trivia skill implementation with real-world patterns

Real-World Example¶

Our documentation is built around a complete, production-ready trivia skill that demonstrates:

• Game Logic: Question management, scoring, and leaderboards
• Visual Interface: APL documents with interactive slides
• Data Persistence: DynamoDB integration for user and game data
• Deployment: AWS Lambda with CDK infrastructure

See the Examples section for the complete implementation.

Requirements¶

• .NET 8.0 or .NET 9.0
• AWS Lambda Runtime (provided.al2023)
• Amazon Alexa Developer Account
• AWS CLI configured with appropriate permissions

Architecture Patterns¶

AlexaVoxCraft follows these architectural patterns:

1. CQRS with MediatR: Separate command and query responsibilities
2. Pipeline Pattern: Composable request/response processing
3. Builder Pattern: Fluent APIs for APL documents and responses
4. Repository Pattern: Data access abstraction for session and user data
5. Dependency Injection: Service registration and lifetime management

Contributing¶

See the main README for contribution guidelines.

License¶

This project is licensed under the MIT License.