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