Setup & usage documentation

Prerequisites

• .NET 10 SDK
• Node.js 20+ (for Nexus.Web)
• SQL Server with an empty database (e.g. Nexus)
• Optional: MinIO for object storage of attachments

Configuration & setup

1. Clone the Nexus repository and restore tools as usual.
2. Copy the development settings template:

   copy src\Nexus.Api\appsettings.Development.json.example src\Nexus.Api\appsettings.Development.json

3. Fill in connection string, JWT signing key, and optional MinIO settings.
4. Do not commit appsettings.Development.json—it is gitignored.

Important settings

Section	Purpose
ConnectionStrings:DefaultConnection	SQL Server for EF Core
Jwt:*	Issuer, audience, signing key, access minutes, refresh days
Seed:EnableRootAdminSeed	Dev-only bootstrap of root admin when none exist
Seed:RootUserName / RootPassword	Dev bootstrap credentials (defaults often root / raven)
Minio:*	Object storage (disabled until configured)
Security:Lockout:*	Failed login max / duration
Communications:*	MessageService, SMTP, Firebase, IMAP defaults
Cors:Origins	Vite origin in development
Tickets:AiScreeningWorker:*	In-process AI screening worker

Run in development

Two processes:

# Terminal 1 – API (HTTPS 7711, HTTP 5511)
dotnet run --project src/Nexus.Api

# Terminal 2 – Web (5173)
cd src/Nexus.Web
npm install
npm run dev

On first API start, EF migrations apply. When seed is configured you typically get:

• Tenants: demo, other
• Host mappings: localhost:5511, localhost:7711, localhost:5173 → demo
• Path/header: /t/demo/…, X-Tenant-Slug: demo
• Root admin when root seed is enabled

Production SPA hosting

cd src/Nexus.Web
npm run build
# copy dist/* → src/Nexus.Api/wwwroot/

The API serves static files and falls back to index.html for client routing. Use your environment’s deploy scripts (Deploy-Nexus.bat, Deploy-Nexus-Full.bat, etc.) as documented in the repo.

Multi-tenancy

Resolution order (first match wins):

1. Host – TenantUrls with MatchType = Host (supports host:port)
2. Path – /t/{slug}/… or /api/t/{slug}/…
3. Header – X-Tenant-Slug or X-Tenant-Id

ITenantContext is scoped per request. EF global filters on tenant entities enforce isolation. Platform entities (Tenant, TenantUrl, AppSetting) are not tenant-filtered.

Tenant branding

Stored as tenant setting keys (brand.displayName, brand.logoUrl, brand.backgroundUrl, brand.primary, brand.primaryForeground). Empty values clear overrides so scaffold defaults apply.

Method	Path	Auth
GET	/api/config/brand	Anonymous (login shell)
PUT	/api/config/brand	TenantAdmin / GlobalAdmin

SPA editor: /config/brand. On save, theme CSS variables and document title refresh without a full reload.

Authentication

• ASP.NET Core Identity + JWT bearer
• Login: username or email → POST /api/auth/login returns access + refresh tokens
• Refresh: POST /api/auth/refresh rotates refresh and issues new access
• Logout: POST /api/auth/logout with optional refresh token body
• Claims include sub, tenant_id, roles, is_global_admin
• Roles: GlobalAdmin, TenantAdmin, User

Failed passwords increment Identity access-failed count; after the configured max (default 5), the account locks for the configured duration (default 15 minutes). Successful login resets the counter.

Using the SPA

After login against a resolved tenant:

1. Confirm tenant brand on the shell (logo/colors/title).
2. Open Boards and Backlog for delivery work; open ticket surfaces for support.
3. Tenant admins: configure brand, communications overrides, and agent API keys under /config/*.
4. Global admins: manage tenants, platform settings, and communications under /admin/*.

Useful routes (auth required unless noted):

Area	SPA path
Boards	/boards, /boards/:id
Backlog / items	/backlog, /items/:id
Work config	/work/brands, /work/products, /work/workspaces, /work/config
Tenant brand	/config/brand
Agent API keys	/config/agent-api-keys
Tenant communications	/config/communications
Platform admin	/admin/*

Work boards

Concept	Behavior
Brand	First-class entity under a tenant (not shell theme)
Backlog	Items for a brand with no board placements
Board	Configurable lanes; M2M with brands; item may sit on multiple boards
Lanes	Types Default / Ready / Test / Done; optional targetStateKey
Items	Product, workspace, HTML description/notes, files, state, priority/effort, custom fields, tags, assignees, tasks, relations, history
Color rules	Tenant defaults; board overrides (tag / keyword / regex)

Human JWT routes under /api/work/*; agent equivalents under /api/agent/work/* (same shapes, audited).

Support tickets

Tickets cover board configuration, email intake, screening settings, and operator workflows. AI screening worker can run in Heuristic or Llm mode; tenant AI policy (Tickets → AI & knowledge) controls gradual auto-send defaults.

Agent ticket routes live under /api/agent/tickets/*. Prefer the about catalog for the authoritative path list for your build.

AI Review & KB Review

Day-to-day operators spend most of their ticket time in two board views and two ticket tabs. Full step-by-step walkthrough: AI & KB Review guide.

AI Review (live drafts)

1. Open Tickets → board view AI review (tickets with AI needs review).
2. Open a ticket → tab AI draft.
3. Check category, confidence, policy, citations, and the draft body.
4. Send draft / Send edited, Accept (no send), or Reject. Optionally grade quality 1–5.
5. Use bulk Accept / Reject / Send drafts on the board for triage batches.

KB Review (knowledge curation)

1. Open Tickets → board view KB review (Pending / In progress).
2. Open a ticket → tab KB review.
3. Set product, quality score, notes, and the gold public reply; save status (Done / Skipped / In progress).
4. Promote the gold message to product knowledge (usually inactive with pending-curation).
5. On Tickets → AI & knowledge, edit and activate snippets so AI screening can cite them.

Agent API

Discovery

• Public: GET /api/agent/about — catalog version + buildNumber + endpoint list
• SPA HTML meta: nexus-agent-api → /api/agent/about

Authentication

• Opaque keys prefixed nxak_… (plaintext shown once at creation)
• Header X-Agent-Api-Key: nxak_… or Authorization: Bearer nxak_…
• Key is bound to one tenant; wrong host/path/header → 403
• Manage keys: SPA /config/agent-api-keys or tenant agent-key APIs

Surface areas (summary)

Area	Path prefix
Discovery	GET /api/agent/about
Tenant	GET /api/agent/tenant
Shell brand	GET/PUT /api/agent/brand
Tenant settings	/api/agent/tenant-settings
Communications	/api/agent/communications (+ send email)
Work brands / products / workspaces	/api/agent/work/…
Boards, items, options, fields	/api/agent/work/…
Tickets	/api/agent/tickets/*

Platform admin

Requires GlobalAdmin. UI under /admin/*. Capabilities include platform settings, communications test tools, tenant CRUD + URL mappings, and global admin users (create, password, unlock, disable).

Tenant communication overrides (TenantAdmin): credentials/endpoints for MessageService, SMTP, Firebase may inherit or override; enabled flags and IMAP remain platform-only.

Tests & health

# Backend
dotnet test Nexus.slnx

# Web e2e (from src/Nexus.Web; API should be running for login tests)
npm install
npx playwright install chromium
npm run test:e2e

Method	Path	Auth
GET	/api/health	No
GET	/api/health/secure	JWT
POST	/api/auth/login	No
GET	/api/tenants/current	No

Architecture map

Nexus/
├── src/
│   ├── Nexus.Domain/           # Pure domain
│   ├── Nexus.Application/      # Vertical slices + MediatR
│   ├── Nexus.Infrastructure/   # EF, Identity, JWT, MinIO, seed
│   ├── Nexus.Api/              # Host + minimal APIs
│   └── Nexus.Web/              # React + Vite + Tailwind
└── tests/
    ├── Nexus.Domain.Tests/
    ├── Nexus.Application.Tests/
    └── Nexus.Integration.Tests/

• Domain stays pure — no EF/HTTP in Domain.
• Vertical slices — features under Application/Features/{Feature}/.
• Tenant isolation — never leak data across tenants.
• Secrets — never commit development secrets.