sparc-coop / blossom

Blossom is an opinionated framework-of-a-framework for .NET 7.0 Web, Mobile, and Desktop development using a single shared codebase (C# and Blazor).

What is Blossom?

Blossom is an opinionated framework-of-a-framework for .NET 7.0 Web, Mobile, and Desktop development using a single shared codebase (C# and Blazor).

OK, what is it really?

Blossom is a hand-crafted framework full of architectural conventions that attempt to remove as much of the boilerplate connective tissue as possible.

Its chief aim is to remove all the drivel it possibly can, so that you may focus more of your creative programming energy on what really matters for your app:

• the logic of the back end, and
• the presentation of the front end.

Everything else should be secondary.

How is a Blossom solution structured?

A typical Blossom solution has three main components:

• one Features project. This project is the main back end API for the application, and contains the vast majority of the application's logic.
• one UI project. This project is the shared front end for Web, Mobile, and Desktop, using Blazor as its underlying architecture.
• (optional) one or more Platforms projects, if you're deploying to multiple platforms. These projects are the deployable units for Web (using Sparc.Platforms.Web) and Android/iOS/Mac/Windows (using Sparc.Platforms.Maui). They are typically very small projects with only platform-specific startup code and platform overrides. The vast majority of the UI code should still exist in the shared UI project.

Get Started with Blossom

Step 1. Create a Blossom Solution with a Features and Web Project

1. Features Project: Create a new .NET 7.0 solution with an ASP.NET Core Empty project (preferably called [YourProject].Features).

Follow the Sparc.Kernel documentation for setup.

2. Web Project: Add a Blazor Web Assembly App project to your solution (preferably called [YourProject].Web).

Follow the Sparc.Platforms.Web documentation for setup.

Step 1a (optional, if you're targeting mobile/desktop platforms): Add a Shared UI project and a MAUI Desktop/Mobile project

1. Shared UI Project: Add a Razor Class Library project to your solution (preferably called [YourProject].UI).

Follow the Sparc.UI documentation for setup.

2. Mobile/Desktop Project: Add a .NET MAUI Blazor App project to your solution (preferably called [YourProject].Maui).

Follow the Sparc.Platforms.Maui documentation for setup.

Step 2. Write your app

1. Create your base entity classes in the Sparc.Features project. Entities are the core classes that your app uses.

Examples of entities are Order, User, Product, OrderDetail, etc. See Sparc.Core documentation for architectural guidance.

2. Create a Feature for each "feature" that your app needs. Features are operations that your app can perform and all of the necessary dependencies around that operation (including database retrieval and persistence and other plugins). Each Feature automatically becomes a separate API endpoint.

Examples of Features are GetOrder, SaveOrder, GetUserProfile, etc. See Sparc.Features documentation for architectural guidance.

3. Create a Blazor Page/Component for each UI Page/Component that your app needs, and place them in the Sparc.UI project (or Sparc.Platforms.Web for web-only projects).

Examples of Pages are Orders/Index.razor, ProductDetail.razor, Profile.razor, etc. Examples of Components are ProductSummary.razor, OrdersList.razor, Avatar.razor, etc. See Sparc.UI documentation for architectural guidance.

4. Call your Features from your UI, using the auto-generated Api class that the framework creates for you.

An Api class is automatically regenerated on each build using the swagger.json file from your Features project, which is also automatically regenerated on each build. This class is typically called [YourProject]Api, eg. PointOfSaleApi, and it automatically contains a method for every Feature you've implemented, eg. await Api.GetOrdersAsync(CustomerId).

5. Run the Features project and appropriate Platform project (normally Platforms.Web for fastest development) locally to test and debug your application.

Step 3. Add Sparc plugins as you need them

Database

The Sparc.Features library comes with a default in-memory implementation of IRepository, so you likely don't even need to set up a database in the initial stages of development. Just inject IRepository<Entity> everywhere as needed, and all data will be loaded from/saved to local memory.

When you are ready to add a real database, simply add the appropriate NuGet package to the Sparc.Features project and configure it in the Startup class.

Sparc currently offers libraries for two database providers:

• Azure Cosmos DB: Sparc.Database.Cosmos

• SQL Server / Azure SQL: Sparc.Database.SqlServer

You may also implement your own instance of IRepository<T> if you desire a custom implementation or need a different database provider.

Authentication

All Features by default require some form of authentication, as most real-world API endpoints are private, not public. However, Sparc includes a feature type called PublicFeature which opens up anonymous access to the feature. If you wish to defer user authentication to a later point in the development of your app, you can simply use PublicFeature for all features until you're ready.

When you're ready, simply add the appropriate NuGet package to the Sparc.Features project and configure it per the documentation.

Sparc includes three main options for authentication:

• Azure AD B2C (good for secure OAuth2.0 consumer apps): Sparc.Authentication.AzureADB2C

• Active Directory (good for internal apps): Sparc.Authentication.ActiveDirectory

• Self-Hosted Identity Server (good for custom authentication flows): Sparc.Authentication.SelfHosted

Notifications

To send emails, text messages, and push notifications, Sparc offers two libraries:

• Twilio (for emails and SMS messages): Sparc.Notifications.Twilio

• Azure Notification Hub (for web and mobile push notifications): Sparc.Notifications.Azure

Step 4. Deploy your solution

1. Deploy the Features project to any .NET 6.0 ASP.NET Core-compatible host (eg. Azure App Services).
2. Deploy the Web Platform project to any Web Assembly-compatible host (eg. Azure App Services).
3. Deploy the MAUI Platform project to Google, Apple, and Windows stores, or as desired.

Documentation

Learn more about how to use Sparc.Kernel by visiting the source folder for each package (linked above). Each package contains its own readme for installing and getting started.

Examples / Templates

Sparc.Kernel is the architecture for all of Sparc Cooperative's ongoing projects, including:

• Law of 100 (Features, Platforms.Web, Authentication.AzureADB2C, Database.Cosmos, Notifications.Azure)
• Kodekit (Features, Platforms.Web, Authentication.AzureADB2C, Database.Cosmos)
• Ibis (Features, Platforms.Web, Authentication.AzureADB2C, Notifications.Twilio, Storage.Azure, Database.Cosmos)

Built With

Sparc.Kernel is built on the shoulders of giants:

• Ardalis.ApiEndpoints by @ardalis
• IdentityServer by Duende
• Swagger
• NSwag by @RicoSuter
• Blazored LocalStorage by @chris_sainty
• Bogus by @bchavez
• .NET Core, ASP.NET Core, MAUI, Entity Framework, Cosmos DB, and many more from @microsoft

Contributing

Please read our contributing guidelines here.

blossom's Issues

.AddAuthentication() has to be added to Startup.cs in order for Sparc.Features features to work

.AddAuthentication().AddJwtBearer() has to be added to Startup.cs in order for Sparc.Features features to work at all.

This is added automatically if you configure an authentication provider (SelfHosted or B2C), but not before.

We should figure out a way to have a "default" authentication provider, so that a working project isn't reliant on adding one of the Sparc authentication plugins, and so both Features and Public Features work out of the box.

Investigate use of minimal APIs for Features

Add CQRS/ES options for DB repositories

Investigate using dotnet global version of OpenApiReference

https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-3.1

Create a version of Sparc.Kernel libraries for .NET 7 Preview

Add a prerendering option for Sparc.Platforms.Web

Ideal: If Sparc.Platforms.Web can be the hosted server project for Sparc.Platforms.UI, which serves as "the WASM project" in addition to the Razor Class Library for the MAUI project

Investigate better patterns for TDD using Sparc.Tests

Create mobile notifications plugin

Document all Sparc libraries

Order of priority:

• Sparc.Kernel main Readme
• Sparc.Features
• Sparc.Platforms.Web
• Sparc.Platforms.Maui
• Sparc.Database.Cosmos
• Sparc.Database.SqlServer
• Sparc.Authentication.AzureADB2C
• Sparc.Authentication.SelfHosted
• Sparc.UI
• Sparc.Notifications.Twilio
• Sparc.Notifications.Azure

Create the ability to authorize specific roles

@antoniocorreia has created a base feature that inherits the ApiEndpoint directly to be able to have more direct control over the [Authorize] attribute. Will be published to Sparc.Kernel this week.

.NET 6 Sparcify extension method for WebAplication

Create a new Sparcify extension method for WebAplication based on the existing one for IApplicationBuilder on the ServiceCollectionExtensions to be used with the new .NET 6 web template.

Sparc Visual Studio templates

Create templates for each project and Multi-project templates for Maui/Web project

Create Sparc.Conversations (or similar idea in Core) with an all-encompassing agnostic notification framework

Find a better implementation for the SwaggerOperation attribute for a better Swagger UX

Create conventions for versioning the API, especially for mobile apps

Goals:

• Less redundancy
• Less mess
• Better developer experience

Sparc.Platforms.*: Add an ApiResolver that conditionally adds the access token if available, but calls anonymously if not

Currently the only options are Api. and PublicApi()., which force an access token to be available, or don't pass the access token at all. So the UI has to always distinguish between whether an access token is available and call the right thing for the right circumstance.

For use in PublicFeature that also needs access to the User object if available.

CosmosDbRepository/SqlRepository isn't registered in DI after Startup runs

In .NET 6, .AddScoped(typeof(IRepository<>), typeof(CosmosDbRepository<>)) has to be added to the Sparc project's Startup file in order for the repository to be registered in DI. Otherwise the repository lookup fails at runtime. This line of code already exists in both ServiceCollectionExtensions for Cosmos & SQL, so it seems .NET 6 might have messed w/ some DI things as far as ordering and parallel registration.

Simplify appsettings.json settings for Azure B2C

Sparc.Database.Cosmos UpdateAsync() is not deleting any removed/replaced owned entities

entity.OwnedEntities.Remove(x);
await Repository.UpdateAsync(entity);

Owned entity is not removed

Add Analytics plugin (starting with Google and App Insights)

• Google primarily for front end, App insights for back end
• Track button clicks, events, etc. in Blazor
• A better way to track exceptions for app insights within features

Generate swagger.json and NSwag client code at design time

See https://stackoverflow.com/a/65427467 for potential guidance