Krafter

A modern .NET 9 full-stack platform built with Vertical Slice Architecture (VSA), multi-tenancy, and Blazor WebAssembly — designed for efficient AI-assisted feature development.

⚡ TL;DR Quick Start

Install tools (once)

dotnet-ef: dotnet tool install --global dotnet-ef
Kiota CLI (optional for client regen): dotnet tool install --global Microsoft.Kiota.Cli

Run Aspire orchestration (starts PostgreSQL, dynamic ports)

dotnet run --project aspire/Krafter.Aspire.AppHost/Krafter.Aspire.AppHost.csproj

Copy DB connection string from Aspire Dashboard → PostgreSQL (format: Host=localhost;Port=XXXXX;Username=postgres;Password=postgres;Database=krafterDb)
Stop krafter-api service in Aspire (unlocks Backend assembly)
Set migration connection string

EITHER update src/Backend/appsettings.Local.json → ConnectionStrings:KrafterDbMigration
OR set env var: ConnectionStrings__KrafterDbMigration="Host=localhost;Port=XXXXX;Username=postgres;Password=postgres;Database=krafterDb"

Apply migrations (once)

cd src/Backend
dotnet ef database update --context KrafterContext
dotnet ef database update --context TenantDbContext
dotnet ef database update --context BackgroundJobsContext

Restart krafter-api in Aspire and open URLs

Aspire Dashboard: https://localhost:17285
Backend API: https://localhost:5199
Swagger UI: https://localhost:5199/swagger
Blazor UI: https://localhost:7291

Note: Ports are dynamic per run; use the Aspire Dashboard values.

🎯 Overview

Krafter is a production-ready, enterprise-grade full-stack platform built with .NET 9, combining modern architectural patterns with cutting-edge technologies. It provides a solid foundation for building scalable, multi-tenant SaaS applications with rich user interfaces.

What Makes Krafter Special?

🏗️ Vertical Slice Architecture (VSA) - Backend organized by features, not layers
🌐 Hybrid Blazor - WebAssembly + Server rendering for optimal performance
🏢 Multi-Tenancy - Complete tenant isolation at the database level
🔐 Permission-Based Security - Fine-grained authorization with JWT
⚡ Real-Time Updates - SignalR integration for live notifications
📊 Observability - OpenTelemetry with Aspire orchestration
🎨 Modern UI - Radzen components with theming support

🏛️ Architecture

Solution Architecture Diagram

Project Dependencies Diagram

✨ Key Features

🏗️ Architecture

Vertical Slice Architecture (VSA) - Features organized by business capability
Clean Code - Single Responsibility, DRY, SOLID principles
Auto-Registration - Handlers, services, and routes discovered via markers
Response Pattern - Consistent Response<T> wrapper for all operations

🔐 Security

JWT Authentication - Secure token-based authentication
Google OAuth - External authentication integration
Permission-Based Authorization - Fine-grained access control
Multi-Tenancy - Complete tenant isolation at DB level
Token Refresh - Automatic token rotation

🎨 User Interface

Blazor Hybrid - WebAssembly + Server rendering
Radzen Components - 70+ professional UI components
Theme Support - Light/Dark/Auto modes with WCAG compliance
Responsive Design - Mobile and desktop optimized
Code-Behind Pattern - Clean separation of markup and logic
Kiota Client - Type-safe, auto-generated API client

📊 Data & Storage

EF Core - PostgreSQL & MySQL support
Multi-Database - Separate contexts for tenants, jobs, and main data
Migrations - Code-first database schema management
Soft Delete - Recoverable data deletion

⚡ Performance & Scalability

Background Jobs - TickerQ for async processing
SignalR - Real-time bi-directional communication
Redis Cache - Distributed caching support
Pagination - Efficient data loading
Debouncing - Optimized search and filtering

🔍 Observability

.NET Aspire - Orchestration and service discovery
OpenTelemetry - Distributed tracing and metrics
Structured Logging - Comprehensive application logs
Health Checks - Service health monitoring

🚀 DevOps

NUKE Build - Automated build pipeline
Docker Support - Containerized deployment
GitHub Actions - CI/CD automation
Auto Deployment - Webhook-triggered updates

🛠️ Technology Stack

Backend

.NET 9 - Latest .NET framework
ASP.NET Core - Minimal APIs
Entity Framework Core 9 - ORM
ASP.NET Core Identity - User management
FluentValidation - Input validation
TickerQ - Background job processing
SignalR - Real-time communication

Frontend

Blazor WebAssembly - Client-side SPA
Blazor Server - Server-side rendering
Radzen Blazor - UI component library
Microsoft Kiota - API client generation
Blazored LocalStorage - Browser storage
FluentValidation.Blazor - Client-side validation
Mapster - Object mapping

Infrastructure

.NET Aspire - Cloud-native orchestration
OpenTelemetry - Observability
Redis - Caching (optional)
PostgreSQL / MySQL - Database
Docker - Containerization
NUKE - Build automation

🚀 Getting Started

Prerequisites

Install Tools

EF Core tools: dotnet tool install --global dotnet-ef
Kiota CLI (optional, for API client regen):
- dotnet tool install --global Microsoft.Kiota.Cli

Quick Start

Clone the repository

git clone https://github.com/AditiKraft/Krafter.git
cd Krafter

Restore packages
```
dotnet restore
```

Run with Aspire (starts DB and services)

dotnet run --project aspire/Krafter.Aspire.AppHost/Krafter.Aspire.AppHost.csproj

Apply database migrations (quick path)
- Open Aspire Dashboard → copy PostgreSQL connection string
- Stop krafter-api service
- Set ConnectionStrings__KrafterDbMigration (or update src/Backend/appsettings.Local.json)
- Run:
```
cd src/Backend
dotnet ef database update --context KrafterContext
dotnet ef database update --context TenantDbContext
dotnet ef database update --context BackgroundJobsContext
```
- Restart krafter-api
Configure secrets (see Secrets and Configuration)
Access the application
- Aspire Dashboard: https://localhost:17285
- Backend API: https://localhost:5199
- Swagger UI: https://localhost:5199/swagger
- Blazor UI: https://localhost:7291
Default Credentials

On first run, the application seeds a default admin account:
- Email: admin@krafter.com
- Password: Admin@123
⚠️ Important: Change the default password immediately in production!

Database Migrations Workflow

Before running the application for the first time, you need to set up the database and apply migrations.

Prerequisites for Migrations

✅ Aspire orchestration must be running (provides PostgreSQL database)
✅ Backend API must be stopped before running migration commands
✅ Connection string configured in appsettings.Local.json or via environment variable

Step-by-Step Migration Process

1. Start Aspire Orchestration

dotnet run --project aspire/Krafter.Aspire.AppHost/Krafter.Aspire.AppHost.csproj

This starts PostgreSQL and generates a dynamic connection string.

2. Copy Database Connection String

Open the Aspire dashboard (typically https://localhost:17285)
Navigate to the PostgreSQL resource
Copy the connection string
Format: Host=localhost;Port=XXXXX;Username=postgres;Password=postgres;Database=krafterDb

3. Stop the Backend API

In the Aspire dashboard, stop the krafter-api service
Why? The Backend assembly is locked when the API is running, preventing EF Core migration tools from accessing it

4. Update Migration Connection String

Open src/Backend/appsettings.Local.json and update the KrafterDbMigration connection string:

{
  "ConnectionStrings": {
    "KrafterDbMigration": "Host=localhost;Port=52961;Username=postgres;Password=postgres;Database=krafterDb"
  }
}

Important: Replace Port=52961 with the port from your Aspire dashboard (it changes on each run).

Tip: You can also set the environment variable ConnectionStrings__KrafterDbMigration instead of modifying the file.

5. Apply Migrations

Navigate to the Backend project directory and apply migrations:

cd src/Backend

# Apply all migrations
dotnet ef database update --context KrafterContext
dotnet ef database update --context TenantDbContext
dotnet ef database update --context BackgroundJobsContext

6. Restart Backend API

In the Aspire dashboard, restart the krafter-api service
Or restart the entire Aspire orchestration

Your database is now ready! 🎉

Why This Workflow?

Requirement	Reason
Aspire Running	Database connection strings are dynamically assigned by Aspire (ports change on each run)
Backend Stopped	EF Core migration tools compile and load the Backend assembly. If the API is running, the assembly is locked
appsettings.Local.json	With Backend stopped, we configure the connection string in appsettings or environment variables

Creating New Migrations (For Development)

When you add new features that require database changes:

cd src/Backend

# Create a new migration
dotnet ef migrations add <MigrationName> --context KrafterContext

# Apply the migration
dotnet ef database update --context KrafterContext

Troubleshooting

Issue	Cause	Solution
"Unable to create DbContext"	Backend API is running	Stop the Backend API in Aspire dashboard
"Database connection failed"	Wrong port or Aspire not running	Verify Aspire is running and copy the correct connection string from dashboard
"Could not find DbContext"	Wrong working directory	Ensure you're in `src/Backend` directory
"Migration already exists"	Duplicate migration name	Use `dotnet ef migrations remove --context <ContextName>`
`dotnet-ef` not found	EF tools not installed	Run `dotnet tool install --global dotnet-ef`

Secrets and Configuration

Before running the application, configure the following secrets and settings:

Required Configuration

aspire/Krafter.Aspire.AppHost/appsettings.json

Parameters:postgresUsername = {YOUR_POSTGRES_USERNAME}
Parameters:postgresPassword = {YOUR_POSTGRES_PASSWORD}

src/Backend/appsettings.json

TickerQBasicAuth:Username = {TICKERQ_BASIC_AUTH_USERNAME}
TickerQBasicAuth:Password = {TICKERQ_BASIC_AUTH_PASSWORD}
SecuritySettings:JwtSettings:Key = {JWT_SIGNING_KEY}

src/UI/Krafter.UI.Web/appsettings.Development.json

Jwt:Key = {JWT_SIGNING_KEY} (MUST be identical to backend JWT key)

src/UI/Krafter.UI.Web.Client/wwwroot/appsettings.json

RemoteHostUrl = {YOUR_BACKEND_HOST}
Authentication:Google:ClientId = {YOUR_GOOGLE_CLIENT_ID} (optional, for Google OAuth)

⚠️ Important: The JWT signing key must be exactly the same for the Backend and the UI server host. This ensures tokens issued by the backend validate correctly during server-side rendering and prerendered Blazor scenarios.

Quick commands via user-secrets (recommended for dev)

From the Backend project (src/Backend):

# initialize once (if needed)
dotnet user-secrets init

# set JWT and TickerQ basic auth
dotnet user-secrets set "SecuritySettings:JwtSettings:Key" "<long-random-32+ chars>"
dotlet user-secrets set "TickerQBasicAuth:Username" "<username>"
dotlet user-secrets set "TickerQBasicAuth:Password" "<password>"

From the Blazor Server host (src/UI/Krafter.UI.Web):

# initialize once (if needed)
dotnet user-secrets init

# JWT key must match Backend
dotnet user-secrets set "Jwt:Key" "<same-long-random-key-as-backend>"

📁 Project Structure

Krafter/
├── aspire/                          # Aspire orchestration
│   ├── Krafter.Aspire.AppHost/     # Orchestration host
│   └── Krafter.Aspire.ServiceDefaults/ # Shared configuration
├── src/
│   ├── Backend/                     # ASP.NET Core API (VSA)
│   │   ├── Features/               # Vertical slices (Auth, Users, Roles, Tenants)
│   │   ├── Infrastructure/         # Persistence, Jobs, Multi-tenancy
│   │   ├── Common/                 # Shared utilities, permissions
│   │   ├── Api/                    # API configuration, middleware
│   │   └── Program.cs             # Entry point
│   └── UI/
│       ├── Krafter.UI.Web.Client/  # Blazor WebAssembly
│       │   ├── Features/          # Feature-based UI components
│       │   ├── Infrastructure/    # Services, Auth, API clients
│       │   ├── Common/            # Shared components, models
│       │   └── Client/            # Auto-generated Kiota client
│       └── Krafter.UI.Web/        # Blazor Server host
├── build/                          # NUKE build project
├── .github/                        # GitHub Actions workflows
└── README.md                       # This file

For detailed structure, see .github/copilot-instructions.md

📖 Development Guide

Adding a New Feature

Backend (VSA Pattern):

Create feature folder: Features/<Feature>/
Add operation files (e.g., Create<Feature>.cs, Get<Feature>s.cs)
Add entity to Features/<Feature>/_Shared/<Entity>.cs
Update KrafterContext.cs with new DbSet
Create EF configuration in Infrastructure/Persistence/Configurations/
Run migration: dotnet ef migrations add Add<Feature>
Add permissions to Common/Auth/Permissions/KrafterPermissions.cs

UI (Blazor):

Create feature folder: Features/<Feature>/
Add list page: <Feature>s.razor + <Feature>s.razor.cs
Add form dialog: CreateOrUpdate<Feature>.razor + .razor.cs
Add route constant to Common/Constants/KrafterRoute.cs
Update permissions in Common/Permissions/KrafterPermissions.cs
Update Infrastructure/Services/MenuService.cs for navigation
Regenerate Kiota client: kiota update

For complete guidelines, see Development Workflow

Key Commands

# Build solution
dotnet build

# Run tests
dotnet test

# Create migration
dotnet ef migrations add <Name> --project src/Backend --context KrafterContext
dotnet ef migrations add <Name> --project src/Backend --context BackgroundJobsContext
dotnet ef migrations add <Name> --project src/Backend --context TenantDbContext

# Update database
dotnet ef database update --project src/Backend --context KrafterContext
dotnet ef database update --project src/Backend --context BackgroundJobsContext
dotnet ef database update --project src/Backend --context TenantDbContext

# Regenerate Kiota API client (run from the Client folder containing kiota-lock.json)
cd src/UI/Krafter.UI.Web.Client/Client
kiota update
# Or from repo root:
# kiota update --lock-file-path src/UI/Krafter.UI.Web.Client/Client/kiota-lock.json

🐳 Deployment

Docker Deployment

Build images:

dotnet publish src/Backend/Backend.csproj -c Release -p:PublishProfile=DefaultContainer
dotnet publish src/UI/Krafter.UI.Web/Krafter.UI.Web.csproj -c Release -p:PublishProfile=DefaultContainer

CI/CD with GitHub Actions

The project includes automated CI/CD pipelines that:

Build and test on every push
Create Docker images for main and dev branches
Push images to GitHub Container Registry
Trigger deployment webhooks

See .github/workflows for configuration.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Follow the coding conventions in copilot-instructions.md
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Convention

Use Conventional Commits:

feat(scope): add new feature
fix(scope): fix bug
docs(scope): update documentation
refactor(scope): refactor code
test(scope): add tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

.NET Team - For the amazing .NET platform
Radzen - For the excellent Blazor components
Microsoft Kiota - For the API client generator
NUKE Build - For the build automation framework

📞 Support

Documentation: Copilot Instructions
Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ by Aditi Kraft

⭐ Star this repository if you find it helpful!

Name		Name	Last commit message	Last commit date
.claude		.claude
.devcontainer		.devcontainer
.github		.github
.nuke		.nuke
aspire		aspire
build		build
docs		docs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
COMPONENT_REVIEW.md		COMPONENT_REVIEW.md
DAISYUI_BLAZOR_COMPONENTS.md		DAISYUI_BLAZOR_COMPONENTS.md
DAISYUI_BLAZOR_COMPONENTS_PART2.md		DAISYUI_BLAZOR_COMPONENTS_PART2.md
DAISYUI_REFACTORING_PROGRESS.md		DAISYUI_REFACTORING_PROGRESS.md
Krafter.sln		Krafter.sln
Krafter.sln.DotSettings		Krafter.sln.DotSettings
Krafter.slnx		Krafter.slnx
LICENSE		LICENSE
README.md		README.md
RLVDATAGRID_SPECIFICATION.md		RLVDATAGRID_SPECIFICATION.md
build.cmd		build.cmd
build.ps1		build.ps1
build.sh		build.sh
claude.md		claude.md

Latest commit

History

Folders and files

Repository files navigation