nsail-stack

skill
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in .github/workflows/review.yml
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

NSail Stack: a .NET modular-monolith framework (messaging, data, security, Blazor + React clients).

README.md

NSail

NSail Stack

NuGet
CI
License: MIT

A framework for modular monoliths on .NET 10. You declare an operation once, as a message, and
the Stack derives the rest of it: the HTTP endpoint, the dependency-injection wiring, the typed
client a Blazor page sends it through, the TypeScript a React client imports, and the permission
it demands. Data runs on EF Core over PostgreSQL; the UI is Blazor components (MudBlazor
underneath, never in your API) and React packages that speak the same messages.

It is the foundation of the NSail products, published here as MIT
NuGet packages.

Status: pre-release (0.x). Every merge to main ships a new version. The API still moves;
pin a version and read the changes before you bump it.

Start here

AI first

The Stack is built with Claude Code and written so an agent can
follow it. The architecture is strict and it is written down as doctrine — how a message is
shaped, how data is mapped, how tenancy filters, how a screen places its actions and its refusals
(start at the principles; the
routing table says which page answers which area).
The same pages ship as a plugin, with skills for the everyday work (new-message, new-mapping,
new-icon, convert-to-nsload, test-harness), so an agent building on the Stack reads the same
rules a person does:

claude plugin marketplace add nsail-ar/nsail-stack
claude plugin install nsail-stack@nsail

Pin the plugin at the same tag as your packages, so the pages describe the code you compile
against. For one session from a checkout: claude --plugin-dir <checkout>/plugins/nsail-stack.
This repository is developed the same way: CLAUDE.md is what an agent reads before it
edits anything.

The Stack

Each area has its own README with its packages, its registration calls and every option it
reads. Start with Getting started; come here when you need the detail.

Messaging

An operation is a message; one door, Mediator, sends it; a handler answers it. Events
(Publish/Subscribe), a durable queue ([Queue]), server push over SignalR or SSE, and the
HTTP endpoints and clients all ride that seam.
NSail.Messaging · .Annotations · .Runtime · .Http · .WebApi · .SignalR · .Sse · .Queue
→ Messaging · Injection

Generation

What can be derived is never written: DI registrations, endpoints, typed clients, permission
handlers, entity mappers and the TypeScript contract all come from a partial method marked
[Generated(...)].
NSail.Messaging.SourceGenerator (the analyzer) · NSail.TypeScriptGenerator · NSail.SourceGeneration.Annotations · .Testing
→ Generation

Data and mapping

EF Core over PostgreSQL, configured once for the whole model: row version, audit stamps, tenancy
and the org filter. The mapper writes message graphs onto entities and projects entities into
rows, generated at compile time with the semantics of Detached Mapper.
NSail.Data · NSail.Data.Testing · NSail.Mapping · NSail.Mapping.Annotations
→ Data · Mapping

Security

Policies over messages: may this caller send this message with these values? Absence is denial.
NSail.Security · NSail.Security.Annotations
→ Security

UI and components

Blazor components that say what the user means (NsTextField, NsSubmit), with MudBlazor
underneath and never in your API; labels and validation derive from the message a screen binds.
For React, @nsail/stack and @nsail/ui speak the same messages from the TypeScript the build
writes.
NSail.Components · .Mud · .DaisyUI · @nsail/stack · @nsail/ui
→ Components · React

Hosting

One call on the builder and one on the app give a host the runtime, error handling, telemetry,
tenant walls, throttling and Swagger.
NSail.BaseServices.WebApi · .WebApp · .Wasm · NSail.Configuration · NSail.Telemetry
→ BaseServices · Configuration · Telemetry

Harness

A local dispatcher for an AI crew: it reads a board, plans the next work finishing before
starting, and runs analysts, builders, reviewers, releases and QA walkers on the machine.
NSail.Harness · .Sdk · .GitHub · .Claude · .Hosting
→ Harness

Services

  • Localization and Metadata — texts per language, keyed from the namespace.
    → Localization · Metadata
  • Settings — typed settings read and saved through one manager.
    → Settings
  • Background — recurring jobs and deferred work.
    → Background
  • Backup — attended backup and restore of a whole install.
    → Backup
  • Exporting — a list read out as a file.
    → Exporting
  • Storage — put, get, list and delete an object, on the host's disk, an S3-compatible
    bucket or a git repository, with its settings screen.
    → Storage

Foundations

The error model, paging, the wire's JSON contract and the small value types every area shares.
NSail.Types · NSail.BclExtensions · NSail.Injection.Annotations
→ Types

Install

Every Stack project is a package on nuget.org. Pin one
version for all of them, and reference the source generator as an analyzer that does not flow to
your consumers:

<PropertyGroup>
  <!-- the latest version on the NuGet badge above -->
  <NSailStackVersion>0.1.x</NSailStackVersion>
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="NSail.Messaging.WebApi" Version="$(NSailStackVersion)" />
  <PackageReference Include="NSail.Messaging.SourceGenerator" Version="$(NSailStackVersion)" PrivateAssets="all" />
</ItemGroup>

The published versions are this repository's v* tags. The React packages are on npm at the
same version as the NuGet packages; pin them together. They ship ES modules for a bundler (Vite,
webpack), with their types.

What a feature looks like

A message names its route, carries its validation, and says what it answers:

[Http(Post, "api/sample/contacts")]
public class CreateContact : IMessage
{
    public required Guid Id { get; set; }

    [Required]
    [MaxLength(100)]
    public string Name { get; set; } = string.Empty;

    [Range(0, 100)]
    public int Rating { get; set; }
}

[Http(Get, "api/sample/contacts")]
public class ListContacts : PagedMessage, IMessage<DataPage<ContactRow>>
{
    [SearchTerm]
    public string? Search { get; set; }
}

A handler answers it. Nothing registers the handler or maps the endpoint by hand — the source
generator does both:

[Injectable]
public sealed class ContactHandler : IHandler<CreateContact>, IHandler<ListContacts, DataPage<ContactRow>>
{
    public async Task Handle(CreateContact message, CancellationToken cancellationToken = default) { ... }

    public async Task<DataPage<ContactRow>> Handle(ListContacts message, CancellationToken cancellationToken = default) { ... }
}

A Blazor page sends the same type — over HTTP from WebAssembly, in process on the server — and
the form validates it with the message's own annotations, on both sides:

@page "/contacts/new"
@attribute [Authorize<CreateContact>]
@inherits NsPage

<NsForm TModel="CreateContact" Model="_model" OnSubmit="OnSubmit">
    <NsPanel>
        <Content>
            <NsTextField @bind-Value="_model.Name" AutoFocus />
            <NsNumericField TValue="int" @bind-Value="_model.Rating" />
        </Content>
        <Footer>
            <NsSubmit />
        </Footer>
    </NsPanel>
</NsForm>

And a React client imports the TypeScript the build writes from those same messages:

import { useMediator } from "@nsail/stack";
import { DeleteContact } from "../sdk";

await mediator.send(DeleteContact, { id: row.id });

Labels, field names and refusals come from one string catalog keyed by the message, so the two
clients and the server say the same words.

Try it: the Sample

src/Stack/Sample is a contacts app — one API, a Blazor
client and a React client over it — built from the Stack alone. It touches every field kind a
form draws and every way a save is refused: client validation, server validation, not found, and
a concurrency conflict.

You need the .NET 10 SDK, Node.js with npm, and a
PostgreSQL server on localhost (user postgres, password in PGPASSWORD).

npm install
dotnet build src/Stack/Sample/NSail.Sample.Web
dotnet run --project src/Stack/Sample/NSail.Sample.Web --launch-profile http

Open http://localhost:4001 for Blazor and http://localhost:4001/react for React. The first
run creates the database.

Repository layout

Path What is there
src/Stack/ One folder per area, one project per package
src/Stack/React/ The @nsail/stack and @nsail/ui React packages
src/Stack/Sample/ The example app
test/Stack/ Unit, component (bUnit) and PostgreSQL-backed tests
plugins/nsail-stack/ The doctrine and the skills, as a Claude Code plugin

Contributing

npm install
dotnet build NSail.sln
dotnet test NSail.sln

The data tests need PostgreSQL as above (PGHOST and PGPORT override the host and port).
Read the doctrine page for the area before you change it, and change the page in the same pull
request as the code: CLAUDE.md holds the rules every change keeps, including the
license header each source file opens with. Pull requests build, test and pack, and publish
nothing; a merge to main publishes every package as the next 0.1.<n> and tags the commit
(ci.yml).

License

MIT © Leonardo Porro and Emmanuel Arias.

Reviews (0)

No results found