Microscope Boilerplate

An opiniated started kit for product engineering teams

Documentation

Requirements

dotnet 8 SDK
nodejs 16+
docker engine

Available templates

mcsp_distributed
mcsp_bff_ssr_blazor
mcsp_desktop
mcsp_cli
mcsp_doc

mcsp_distributed

Distributed architecture oriented

✅ blazor wasm
✅ rest & graphql sdk
✅ bff & api gateway
✅ api "TodoApp" service
✅ IAM
✅ Storage
✅ Postgres database
✅ OpenTelemetry
✅ Bus

mcsp_bff_ssr_blazor

Blazor frontend + BFF pattern

✅ Material UI (MudBlazor)
✅ Custom endpoint
✅ Server side rendering (Blazor)
✅ OIDC / Cookie authentication (Keycloak)
✅ Proxying API (Yarp)
✅ GraphQL gateway (HotChocolate)
✅ Auto generated SDK (StrawberryShake)
✅ Light / Dark theme
✅ I18N
✅ Feature management
✅ Docker

mcsp_doc

Documentation as code web application

✅ web app
✅ vitepress
✅ markdown & mermaid
✅ templates (#product, #ADR, #PRD, #guidelines, ...)
✅ opiniated guidelines

mcsp_cli

Console app with CLI & UI

✅ Cocona CLI
✅ Spectre.Console UI
✅ Commands folder & sample

mcsp_desktop

Cross platform desktop app

✅ Avalonia
✅ material ui & icons
✅ CommunityToolkit.MVVM

Installation

Get source code

git clone https://github.com/bhtz/microscope-boilerplate.git

Install & uninstall microscope dotnet templates

cd microscope-boilerplate/templates
dotnet pack
dotnet new install ./bin/Release/Microscope.Boilerplate.1.0.0.nupkg
dotnet new uninstall Microscope.Boilerplate

Install & uninstall microscope dotnet tool

cd microscope-boilerplate/tool
dotnet pack
dotnet tool install --global --add-source ./nupkg Microscope.Boilerplate.Tool.CLI
dotnet tool uninstall --global  Microscope.Boilerplate.Tool.CLI

Distributed template

Create new distributed solution

dotnet new mcsp_distributed -n Acme.AwesomeProject

Create new distributed solution with CLI

dotnet new mcsp_distributed -n Acme.AwesomeProject -C

Create new distributed solution with Terraform IAC setup

dotnet new mcsp_distributed -n Acme.AwesomeProject -T

Run solution (with docker compose)

cd Acme.AwesomeProject/src/IAC/Docker
docker-compose up

Run solution (with Aspire)

cd Acme.AwesomeProject/src/IAC/Aspire/Microscope.Boilerplate.IAC.Aspire

CLI template

Create new CLI project

dotnet new mcsp_cli -n Acme.CLI

Doc template

Create new documentation as code project

dotnet new mcsp_doc -n Acme.Doc

Create new documentation as code project with default guidelines

dotnet new mcsp_doc -n Acme.Doc -G

Build

Build solution

dotnet build

Build solution containers

dotnet publish -p:PublishProfile=DefaultContainer

Build solution containers for arm64

dotnet publish -r linux-arm64 -p:PublishProfile=DefaultContainer

Build CLI containers for arm64

cd src/Clients/CLI/Microscope.Boilerplate.Clients.CLI
dotnet publish -r linux-arm64 /t:PublishContainer

Run solution

cd src/IAC/Docker
docker-compose up

Go to app

open Boilerplate app

Documentation

Build documentation

cd templates/docs/Microscope.Boilerplate.Doc
npm run docs:build

Run solution documentation (vitepress)

Install NPM packages

cd ./src/Docs/Microscope.Boilerplate.Docs
npm i

Dev documentation

npm run docs:dev

Dev slides (revealjs)

npm run slides:dev

Build docs & run

npm run docs:build
dotnet run

Solution

Environments

export ASPNETCORE_ENVIRONMENT=Development
export ASPNETCORE_ENVIRONMENT=Production

SDK generation

you will need to run todoapp api first for this

cd src/Clients/SDK/Microscope.Boilerplate.Clients.SDK.GraphQL
dotnet graphql update
dotnet build

EF Core Tools

Navigate to infrastructure project

cd src/Services/TodoApp/Infrastructure/Microscope.Boilerplate.Services.TodoApp.Infrastructure/

Add migration

dotnet ef --startup-project ../../Interface/Microscope.Boilerplate.Services.TodoApp.Api/ migrations add InitialCreate -o ./Persistence/Migrations

Update database

dotnet ef --startup-project ../../Interface/Microscope.Boilerplate.Services.TodoApp.Api/ database update

Export SQL

dotnet ef --startup-project ../../Interface/Microscope.Boilerplate.Services.TodoApp.Api/ migrations script > ./Scripts/TodoApp.sql

IAC (experimental)

ASPIRE

Publish Aspire manifest

cd templates/src/IAC/Aspire/Microscope.Boilerplate.IAC.Aspire
dotnet run --publisher manifest --output-path manifest.json

TERRAFORM

Install Terraform & Azure CLI

brew update
brew tap hashicorp/tap
brew install azure-cli
brew install hashicorp/tap/terraform

Init

terraform init
terraform plan
terraform apply

PULUMI (absolete)

Install Pulumi & Azure CLI

brew update
brew install azure-cli
brew install pulumi/tap/pulumi

Azure CLI login

az login

Set azure location (optional)

cd ./src/IAC/Pulumi/Microscope.Boilerplate.IAC
pulumi config set azure-native:location westus2

Deploy stack on Azure

pulumi up

E2E Tests

Setup environment

Register a new E2E test user on keycloak IAM
username: admin@microscope.io
password: microscope

Run End to End tests

cd ./src/Clients/E2E/Microscope.Boilerplate.Clients.E2E
dotnet test

Run End to End tests with GUI

cd ./src/Clients/E2E/Microscope.Boilerplate.Clients.E2E
HEADED=1 dotnet test