Sora Framework - Developer Guide

Built for Developer Flow

Complex enterprise patterns shouldn't break your concentration. Sora modules snap together and auto-configure, so you stay in the zone.

Auto-Discovery Magic

Want a ready-to-use API? Add Sylin.Sora.Web. MongoDB? Snap in Sylin.Sora.Data.Mongo and done. It discovers defaults, sets up structures, handles scaffolding—so you don't have to.

Reduced Cognitive Load

Stop remembering 47 different setup steps. Sane defaults get you productive immediately. Customize when you need to, not because you have to.

Zero Scaffolding

No more endless configuration files, startup registrations, or repetitive CRUD controllers. Define entities, get APIs automatically.

Cloud Native

Built for containers, microservices, and cloud deployment. Health checks, observability, and graceful degradation included.

AI Ready

Vector stores, embeddings, and agent endpoints out of the box. Add AI capabilities without the complexity. (Planned)

Production Ready

Battle-tested patterns: CQRS, Event Sourcing, DDD. Comprehensive logging, metrics, and error handling built in.

Get Started in 3 Minutes

1. Install Templates

                                # Install templates first
dotnet new install Sylin.Sora.Templates::0.1.0-preview

# Choose your starting point
dotnet new sora-tiny-api -n MyApi      # JSON storage
dotnet new sora-tiny-app -n MyApp      # SQLite
dotnet new sora-tiny-docker -n MyApp   # MongoDB + Docker
dotnet new sora-tiny-worker -n MyApp   # Background service
                            

2. Define Your Entity

                                public class Todo : Entity<Todo>
{
    public string Title { get; set; } = string.Empty;
    public bool IsCompleted { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}
                            

3. Start Your App

                                var builder = WebApplication.CreateBuilder(args);

// This single line configures everything
builder.Services.AddSora();

var app = builder.Build();

// Auto-discovers modules and sets up endpoints
app.UseSora();

app.Run();

That's It!

You now have:

RESTful API endpoints for Todo
JSON file storage (auto-configured)
CRUD operations with filtering
Health checks and observability
OpenAPI documentation

Module Ecosystem

Each module is a Lego piece that auto-configures when added to your project. Mix and match to build exactly what you need.

Sylin.Sora.Data.Json

File-based storage. Perfect for prototypes and demos.

Sylin.Sora.Data.Sqlite

Embedded SQL database. Zero configuration required.

Sylin.Sora.Data.Mongo

MongoDB adapter with auto-configuration.

Sylin.Sora.Data.Relational

SQL helpers and string-query support.

Sylin.Sora.Web

RESTful APIs, middleware, and web hosting.

Sylin.Sora.Messaging.RabbitMq

RabbitMQ integration for message-driven architecture.

Sylin.Sora.Data.Cqrs

CQRS primitives and command/query patterns.

Sora.AI

Vector stores, embeddings, and AI agent endpoints. (Planned)

See It In Action

Zero-Config CRUD Operations

                                        // Define your entity
public class Product : Entity<Product>
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public string Category { get; set; } = string.Empty;
}

// Use it anywhere
var product = await new Product 
{ 
    Name = "Laptop", 
    Price = 999.99m, 
    Category = "Electronics" 
}.Save();

// Query with filtering
var electronics = await Product.Where(p => p.Category == "Electronics");
var expensive = await Product.Where(p => p.Price > 500);

// Get by ID
var found = await Product.Get(product.Id);
                                    

Automatic REST endpoints created at /api/products

CQRS & Event Sourcing

                                        // Command with validation
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items)
    : ICommand<Order>;

public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, Order>
{
    public async Task<Order> Handle(CreateOrderCommand command)
    {
        // Business logic here
        var order = new Order(command.CustomerId, command.Items);
        
        // Events are automatically captured and published
        order.AddEvent(new OrderCreatedEvent(order.Id, order.Total));
        
        return await order.Save();
    }
}

// Query with projections
public class OrderSummaryQuery : IQuery<List<OrderSummary>>
{
    public string CustomerId { get; set; }
}

public class OrderSummaryHandler : IQueryHandler<OrderSummaryQuery, List<OrderSummary>>
{
    public async Task<List<OrderSummary>> Handle(OrderSummaryQuery query)
    {
        return await OrderSummary.Where(o => o.CustomerId == query.CustomerId);
    }
}
                                    

AI-Powered Features

                                        // Add AI capabilities
builder.Services.AddSora()
    .AddAiDefaults();  // Vector store + embeddings

// AI-searchable entity
public class Document : Entity<Document>, IVectorizable
{
    public string Title { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
    
    // Auto-generates embeddings on save
    public string GetTextForEmbedding() => $"{Title} {Content}";
}

// Semantic search
app.MapPost("/search", async (string query) =>
{
    var results = await Document.SimilaritySearch(query, limit: 10);
    return results.Select(r => new { r.Document.Title, r.Score });
});

// AI agent endpoint
app.MapAgentEndpoints("/ai", config =>
{
    config.WithSystemPrompt("You are a helpful document assistant");
    config.WithVectorStore<Document>();
});
                                    

Automatic endpoints: /ai/chat, /ai/embed, /ai/search

Enterprise Architecture Concerns Made Easy 🧠➡️❤️

😵‍💫 Traditional Enterprise Development

Weeks spent on project setup and configuration
Endless CQRS boilerplate and handler registration
Debugging DI container nightmares at 2 AM
Copy-pasting patterns between microservices
Fighting with event sourcing complexity
Manual health check implementations

🎉 Sora Development Experience

                                    
// Define your business logic
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items) 
    : ICommand<Order>;

// That's it. Sora handles:
// ✅ Command validation & handlers
// ✅ Event sourcing & outbox patterns  
// ✅ API endpoint creation
// ✅ Health checks & observability
// ✅ Multi-store routing
// ✅ Error handling & logging
                                    
                                

From Enterprise Complexity 😰 to Developer Zen 🧘‍♂️

Task	Traditional Enterprise .NET	With Sora Framework
Add CQRS	✗ Research best practices ✗ Install + configure MediatR ✗ Create handler base classes ✗ Wire up 47 registrations ✗ Debug mysterious DI issues	✓ `dotnet add package Sylin.Sora.Data.Cqrs` Handlers auto-generated ✨
Add Database	✗ Choose an ORM ✗ Configure connection strings ✗ Setup DbContext ✗ Create repositories ✗ Handle migrations	✓ `dotnet add package Sylin.Sora.Data.Sqlite` Auto-configured on startup ✨
Create API	✗ Create controller ✗ Write CRUD actions ✗ Add validation ✗ Handle errors ✗ Configure routing	✓ Define entity class REST endpoints auto-generated
Add Logging	✗ Configure providers ✗ Set log levels ✗ Add structured logging ✗ Handle correlation IDs	✓ Included by default Structured, correlated, ready
Health Checks	✗ Install packages ✗ Configure endpoints ✗ Add custom checks ✗ Setup UI/monitoring	✓ Auto-configured for all modules Database, cache, external services

Developer Resources

Documentation

Sample Projects

Start Building Browse Modules