XiHan.BasicApp

Introduction

XiHan.BasicApp is a decoupled frontend/backend system. The backend follows DDD layering — writes go through application services, reads through query services — and application services are exposed directly as REST endpoints by the dynamic API convention. The frontend is Vue 3 + TypeScript + XiHan.UI, and the backend .NET 10 + XiHan.Framework. Identity, permissions, tenancy and auditing are built in, so it works both as the starting point for an admin project and as a reference for full-stack .NET + Vue practice. XiHan.BasicApp is the application layer of the XiHanFun open-source ecosystem, which spans foundation, components and applications.

Documentation

Preview

Tenant selection

User management

User management (dark)

Server monitoring

Preferences

Operation log

Log traceability

About

Mobile:

Features

Identity and authentication

• User, role, department and menu management
• JWT with two tokens (access 120 minutes + refresh 7 days), multi-device sign-in and session management
• Multiple sign-in methods: password, email / SMS code, 2FA (TOTP / email / SMS, combinable as flags)
• Eight first-party OAuth providers built in — GitHub, Gitee, Google, QQ, WeChat, WeCom, DingTalk, Lark — enabled by configuration
• Sign-in protection: first-party SVG captcha (single-use, can be turned off), throttling on both account+IP and IP alone, failure lockout, forced password change after signing in with the default password
• PBKDF2 password hashing (OWASP-recommended iterations); one-time codes are destroyed on consumption and compared in constant time

Permissions

• Three-segment permission codes module:resource:action; the super administrator wildcard is *
• Role hierarchy through a closure table, five data scopes (self / own department / department and children / all / custom), six field-masking strategies
• Static separation of duties: mutually exclusive roles and cardinality constraints, evaluated per constraint group
• Permission requests with approval, revocable temporary delegation, and a change audit trail

Multi-tenancy

• Column-level isolation by default with TenantId=0 reserved for global data; per-tenant databases are also supported
• Globally unique email sign-in that routes the user by membership (console / workbench / tenant picker), with tenant switching at any time
• Platform-mode operations for super administrators, who can step into any tenant
• Runtime gating by tenant edition allowlist; onboarding creates the administrator, roles and grants in one go; downgrading reclaims grants that fall outside the allowlist

Audit logging

• Six independent log streams: access, API, operation, exception, sign-in and entity change
• Automatic masking before persistence (passwords, tokens, secrets, ID numbers and more, with a counter-example allowlist to avoid over-masking); entity changes distinguish create / update / delete / restore
• Traceability timeline: aggregate across log types by trace ID, username, session, IP or user ID

Code generation

• Single-table, tree and master-detail modes: entities, DTOs, APIs and frontend pages in one shot
• Native Scriban templates embedded into the assembly, each with a manual variant; menu permissions, permission seeds, page descriptors and seeders are generated alongside
• Download as a zip or write to disk; writing to disk is off by default and requires an explicit absolute-path allowlist root, with fail-closed path traversal checks

AI

• Provider onboarding and API-key custody (encrypted at rest with DataProtection; chat and embedding models are configurable)
• Prompt library stored in the database, able to override the framework defaults
• Knowledge-base RAG: document ingestion and vector search (Qdrant), isolated per tenant, keeping the raw content so indexes can be rebuilt
• Registered skills automatically become chat tools and MCP tools; knowledge retrieval ships built in, and business skills join by implementing IAiSkill
• Configurable assistants, bridged into the chat page

Platform

• Dynamic APIs: application services are exposed through [DynamicApi] with no controller boilerplate, and Scalar documentation is generated automatically
• One source of truth for menus: the backend PageRegistry registers menu, route, component path, permission code and i18n key together
• Distributed caching end to end (authorization snapshots, edition gating, menus, settings, dictionaries) with precise invalidation on write paths
• Request tracing; two SignalR hubs (notifications and chat)
• Message center: email / SMS / in-app notification templates, overridable per tenant
• Open platform: a built-in OAuth2 / OIDC provider (third-party app registration, user consent) and per-user OpenAPI credentials with signed calls
• Server monitoring (motherboard / CPU / memory / disk / GPU / network / runtime), cache key lookup and pattern-based clearing
• Multi-backend file storage (local / Aliyun OSS / Tencent COS / MinIO), database-backed scheduled jobs, review workflow, i18n (Chinese / English)
• Export center: async tasks with CSV and XLSX writers on a delayed queue

Frontend experience

• Schema-driven list pages: search, table and export generated from configuration, with column settings, density switching, advanced search, saved personal views, row hover previews, tree mode and column resizing
• Permission-, tenant- and preference-aware: pages, fields and actions filtered by permission code with field masking; column and search preferences sync to the backend and stay consistent across devices
• Dynamic-island feedback, tabbed pages, favorites, command-palette global search
• Message center: top banner, sign-in dialog, notification center, with forced reading and role/department targeting
• Preference center: light/dark theme, brand color, layout style and density, synced to the cloud
• Rich text (Tiptap) and markdown editors, visual cron builder, JSON editor/viewer, code editor
• Lock screen, watermark, time zone switching, export center

Tech Stack

Backend: .NET 10 with XiHan.Framework 4.0.0 (SqlSugar, Redis, SignalR, Serilog and Scalar all arrive through the framework). Frontend: Vue 3 + TypeScript + Vite 8 + XiHan.UI + Pinia + Tailwind CSS 4.

Item-by-item lists live in the backend and frontend engineering notes.

Architecture

The system splits into a framework layer, a module layer and the host application; each module follows DDD layering internally (domain / application / infrastructure).

…

…

Removing Optional Modules

An optional module is one backend project plus one src/modules/ directory on the frontend. The per-side steps live in the backend and frontend engineering notes.

⚠️ Removal must be paired with rebuilding the database: seeded menus, permissions, role grants and scheduled jobs are not reclaimed when a module is deleted.

Getting Started

Requirements

One Command with Containers

The repository root ships a docker-compose.yml with five services — PostgreSQL, Redis, Qdrant, backend and frontend:

cp .env.example .env
docker compose up -d

The frontend defaults to http://localhost:8080 and the backend to http://localhost:9708; both ports are configurable in .env.

Backend

git clone https://github.com/XiHanFun/XiHan.BasicApp.git
cd XiHan.BasicApp/backend

dotnet run --project src/main/XiHan.BasicApp.WebHost --launch-profile Development

Then open http://127.0.0.1:9708/scalar for the API documentation. Ports per environment: Development 9708, Production 9709.

The connection string goes into XiHan:Data:SqlSugarCore:ConnectionConfigs in backend/src/main/XiHan.BasicApp.WebHost/appsettings.Development.json. The first start creates the schema and seeds it automatically.

The framework is consumed from NuGet by default, so cloning this repository alone is enough to build. See the backend engineering notes for working on the framework at the same time.

Frontend

cd frontend
pnpm install
pnpm dev

@xihan-ui/* comes from the published npm releases, so cloning this repository on its own and running pnpm install just works — no sibling XiHan.UI checkout required. To debug against the component library sources, temporarily add an overrides block in pnpm-workspace.yaml pointing at link:../../XiHan.UI/ui/packages/*, then remove it; do not commit it.

Default Account

The initial super administrator is superadmin with the password SuperAdmin@123. Override it through Saas:Seed:SuperAdminPassword (environment variable Saas__Seed__SuperAdminPassword). Always override it in production, and change it right after the first sign-in.

Ecosystem

• XiHan.Framework - A fast, lightweight, efficient and thoughtfully built modern modular framework for .NET
• XiHan.UI - A fast, lightweight, efficient and thoughtfully built framework-agnostic component library
• XiHan.BasicApp - A beautifully crafted admin kernel built on .NET and Vue

Acknowledgements

In no particular order.