from Sylin.org

v0.2.18 Early Stage High Impact

Koan Framework

The crystallization emerging from complexity chaos. When teams rebuild identical infrastructure repeatedly, platforms emerge to simplify the madness. Talk to your code, don't fight it.

See Crystallization Join Development

Koan-demo

# The complexity chaos most teams experience:

$ mkdir new-api && cd new-api

$ dotnet new webapi # 47 files created

# Now configure: auth, validation, DB, logging, health...

# 3 hours later, still setting up infrastructure

# Meanwhile, with Koan (crystallization in action):

$ dotnet add package Sylin.Koan.App

$ dotnet run

Entity-first patterns discovered

Islands of Stability created

Ready to talk to your code

Crystallization in Action

When complexity heat builds to cognitive overload, crystallization emerges. Koan represents the abstraction layer that transforms chaos into Islands of Stability.

Heat Buildup Recognition

Teams repeatedly rebuild identical infrastructure: deployment pipelines, validation logic, error handling, observability. This complexity accumulation creates the cognitive overload that signals crystallization opportunity.

Crystallization Moment

Someone materializes an interface that dramatically simplifies the chaos. Koan provides entity-first patterns that reduce cognitive overhead without breaking critical requirements.

Islands of Stability

The abstraction becomes invisible infrastructure, enabling new capabilities that weren't practical at previous complexity levels. Talk to your code naturally.

Early Adopter Impact

Share your real use cases with us. Together we can build patterns that work for your actual needs, creating tools that solve genuine problems rather than theoretical ones.

AI Ready

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

Cycle Continues

Success at this stability level creates new complexity that triggers the next crystallization. Contribute to identifying future heat zones and emerging platform opportunities.

From Chaos to Stability

Experience the crystallization transformation: complexity that overwhelmed teams becomes invisible infrastructure you can talk to naturally.

1. The Complexity Heat

                                # What teams typically face:
mkdir new-api && cd new-api
dotnet new webapi  # 47 files generated

# Then hours of configuration:
# - Entity Framework setup
# - Database migrations
# - Validation attributes
# - Error handling middleware
# - Health check configuration
# - Logging and observability
# - Authentication/authorization
# - API documentation

# Result: 3+ hours before writing business logic
                            

2. The Crystallization

Meanwhile, with Koan (collaborative development):

                                # Add the framework package
dotnet add package Sylin.Koan.App  # v0.2.18
                            

Entity-first patterns that feel natural:

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

    // Everything else handled by crystallized patterns:
    // - ID generation, validation, persistence, API endpoints
    // - All the complexity chaos becomes invisible
}
                            

3. Islands of Stability

The complete application setup:

                                var builder = WebApplication.CreateBuilder(args);

// This single line handles all the complexity:
// Database setup, API generation, validation, error handling
builder.Services.AddKoan();

var app = builder.Build();
app.UseKoan();
app.Run();

// Result: Talk to your code, don't fight it
                            

What you get automatically: RESTful endpoints, validation, error handling, health checks, OpenAPI documentation, and persistence - all from that entity definition above.

Crystallization Complete

What took hours of configuration chaos is now invisible infrastructure:

Cognitive load reduced to entity patterns
Natural conversation with your code
Foundation for next complexity level
Your feedback shapes what we build next
Step-change productivity improvement

Join the Development v0.2.18 - Early stage, high impact

Crystallized Abstractions

Each module represents complexity that teams repeatedly rebuilt until someone crystallized it into invisible infrastructure. Add what you need, ignore the chaos.

Data Persistence Heat

Teams rebuilt file storage, database connections, migrations repeatedly. Crystallized into transparent data access.

API Generation Heat

Endless controller boilerplate, validation, error handling. Crystallized into entity-first endpoints.

AI Integration Heat

Model deployment, prompt management, safety guardrails. Crystallizing into natural AI workflows.

Observability Heat

Logging, metrics, health checks, tracing complexity. Crystallizing into invisible monitoring.

Sylin.Koan.Web

RESTful APIs, middleware, and web hosting.

Sylin.Koan.Messaging.RabbitMq

RabbitMQ integration for message-driven architecture.

Sylin.Koan.Data.Cqrs

CQRS primitives and command/query patterns.

Koan.AI

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

See It In Action

Entity-First Conversation

                                        // Talk to your code naturally
public class Product : Entity<Product>
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public string Category { get; set; } = string.Empty;

    // All complexity chaos becomes invisible:
    // - ID generation, validation, persistence
    // - API endpoints, error handling
    // - Database setup, health checks
}

// Create and save - no repository injection
var laptop = await new Product
{
    Name = "Laptop",
    Price = 999.99m,
    Category = "Electronics"
}.Save(); // Persistence just works

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

// Retrieve by conversation
var found = await Product.Get(laptop.Id);

// No configuration chaos, no boilerplate fights
                                    

Natural conversation with your code, crystallized infrastructure

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.AddKoan()
    .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

Koan Development Experience

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

// That's it. Koan 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 Koan 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.Koan.Data.Cqrs` Handlers auto-generated
Add Database	× Choose an ORM × Configure connection strings × Setup DbContext × Create repositories × Handle migrations	✓ `dotnet add package Sylin.Koan.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