## 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 + TypeScript + XiHan.UI, and the backend .NET + 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 basic application of the XiHanFun open-source ecosystem.
## Documentation
| Destination | Contents |
| --- | --- |
| [Documentation site](https://basicapp.docs.xihanfun.com) | Full guides and topic-by-topic documentation |
| [Backend engineering notes](./backend/README.md) | Structure, project catalog, endpoint exposure, dependencies, local development |
| [Frontend engineering notes](./frontend/README.md) | Stack, monorepo structure, architectural constraints, local development |
## Preview
The shots illustrate the [highlights](#highlights); to try it hands-on, open the [live demo](https://basicapp.xihanfun.com).
Light and dark themes
Every page and component color-checked in both |
One color, a full palette
Material You dynamic color and 21 traditional Chinese presets |
Preference center
Layout, color, density, shortcuts and cloud sync in one place, applied live on your other devices |
Schema-driven list pages
Hover previews, advanced search and column settings out of the box |
Command palette search
Ctrl / ⌘ + K, with pinyin initials, straight to pages and actions |
In-app split view
Two pages side by side, swapped without reloading |
Multi-tenant control center
Switch between platform administration and tenants in one place |
Small screens
Sign-in, dashboard, drawer menu, command palette and Dynamic Island, ready in a phone browser |
Dashboard
Drag widgets into place, with the board layout saved to the cloud |
One TraceId, the whole story
Seven log types on one timeline, with a Sankey view of the flow |
## Highlights
Close to 90 tables, more than 50 pages and over 300 permission codes come built in. This section covers only what sets the project apart; the page-by-page capability list lives in the [feature list](https://basicapp.docs.xihanfun.com/features) on the docs site (Chinese). AI, chat, code generation, workflow and printing are optional modules.
### Experience
- **Light and dark themes**: Not a class toggled at the root — every page and every component has been color-checked in both; switching ripples out from the point you clicked
- **One color, a full palette**: 21 traditional Chinese color presets plus any custom color; Material You dynamic color derives secondary, container and tinted neutral tones from the brand color, so changing it takes no CSS edits
- **Preference center**: Tune 7 layouts, corner radius, density, font size, tab style, page transitions and watermark; preferences, column settings, search habits and dashboard boards sync to the cloud and apply live on your other devices
- **Dynamic Island feedback**: Borrowed from phones — sign-in, uploads, exports, server-side task progress and reconnects gather in a small island at the top, with progress rings and retry buttons inside, instead of a screen full of toasts
- **Schema-driven list pages**: Nearly 50 list pages are generated from one field schema each, with column settings, advanced search, multi-column sorting, hover row previews, tree mode, column resizing and import/export out of the box
- **Command palette search**: Press `Ctrl / ⌘ + K` for fuzzy matching (including Chinese pinyin and initials) that jumps to any page you can access, or runs actions such as switching theme, locking the screen or favoriting the current page
- **In-app split view**: Put two pages side by side and swap them without reloading; pin and drag tabs, and press `Alt + B` for a searchable tab overview
- **Small screens**: On narrow viewports the sidebar becomes a drawer, action buttons collapse to icons and chat switches to a single pane, so it works in a phone browser
- **Motion with an origin**: Dialogs grow out of the button or row that opened them, favorited tabs fly into the favorites bar, and all of it switches off when the OS asks for reduced motion
- **Languages and time zones**: 7 languages (Simplified and Traditional Chinese, English, Japanese, Korean, Hindi, German) across frontend and backend, with times shown in each user's chosen time zone
### Access and security
- **The server owns the session**: Every request reads a server-side permission snapshot instead of trusting token claims, so revocations and forced sign-outs take effect at once; a locked screen answers every request with 423 and resumes after unlocking, no new sign-in needed
- **Field-level security**: Control read, edit and masking (hidden, full mask, partial mask, hash, redact) per role, user or department, enforced on the server and in exports; masked fields cannot be sorted or filtered, so their values cannot be inferred from result order
- **Role inheritance and separation of duties**: Only direct inheritance edges are stored and the full graph is derived, with parent denies flowing down; static separation of duties is checked on role assignment, inheritance changes and request approval, and conflicts are blocked
- **Time-boxed delegation and access requests**: Delegations must carry an expiry and can be revoked at any time; approved requests grant the role or permission automatically
- **Impersonation with guardrails**: A reason is required, sessions expire after 30 minutes by default, high-risk permissions are blocked, everything is audited and a banner stays on screen
- **Authentication, fully stocked**: Passwords, email and SMS codes, TOTP two-factor, 8 external providers (GitHub, Gitee, Google, QQ, WeChat, WeCom, Feishu, DingTalk), and throttling per account + IP and per IP
- **Built-in OAuth2 / OIDC server**: Authorization code with PKCE, token revocation, discovery and JWKS make it a single sign-on hub for your other systems; OpenAPI callers get AK / SK signed credentials
- **One source for menus, routes and permission codes**: The backend PageRegistry declares pages, routes, components, permission codes and buttons in one place; menu seeds and frontend routes derive from it, and tests check that both sides agree
### Multi-tenancy
- **Two isolation modes**: Field-level isolation by default, or a dedicated database for any single tenant (PostgreSQL, MySQL, SQL Server, SQLite or Oracle), provisioned step by step together with its administrator
- **Global data that tenants cannot overwrite**: Platform rows use `TenantId = 0`; tenants can read but not write them, enforced by a write guard in the framework data layer
- **Editions you can sell**: Free, basic, professional and enterprise editions gate features with permission allowlists, and downgrades revoke out-of-range grants automatically; seat and storage quotas are enforced when adding members and uploading files
- **Platform-side operations**: Assign support members into tenants, transfer tenant ownership, and let a background job disable tenants when they expire
### Audit and operations
- **Seven audit log types**: Access, OpenAPI, operation, exception, sign-in, data change and permission change, with passwords and tokens masked before storage, monthly table splitting and scheduled cleanup
- **One TraceId, the whole story**: All seven log types line up on one timeline by TraceId, session, user or IP, with a Sankey diagram for flow and a stacked chart for time distribution
- **Field-by-field change history**: Creates, updates, deletes and restores record before-and-after values and a risk level
- **Reliable message delivery**: Combine in-app, email, SMS and bot channels freely, with per-tenant template overrides; an outbox with atomic claiming, retries and crash recovery, plus SignalR real-time push
- **Exports that respect permissions**: The export center runs in the background as the requesting user, so field masking still applies, and progress streams back to the Dynamic Island
- **Business numbers without duplicates**: Idempotency keys and request fingerprints prevent double allocation, optimistic locking keeps concurrency safe, with batch allocation and time-zone-aware resets
- **Upgrades with a ledger**: Forward SQL scripts record status, duration and errors per version and per database, while maintenance mode answers 503 with `Retry-After` during upgrades
### Optional modules
- **Keep only what you need**: AI, chat, code generation, workflow and printing are each one backend project paired with one frontend directory, removable as a unit (see [Removing optional modules](#removing-optional-modules))
- **Code generation**: Single-table, tree and master-detail modes produce entities, DTOs, APIs and frontend pages in one pass, plus permission codes, menus, export providers and print data sources; generated and hand-written code live in separate files, so regenerating never overwrites your edits
- **Workflow**: A visual designer on AntV X6 with 16 node types, any-of, all-of and sequential approval, reassignment and added signers; state is persisted and recovers after crashes, and instance graphs color each node by status
- **Print designer**: Drag in fields and bind backend data sources and sample data for WYSIWYG templates; silent direct printing works with the desktop client
- **Online chat**: Direct, group and department chats with recall, edit, reply, @mentions, reactions, group read receipts, voice messages and sensitive-word blocking, plus a streaming AI assistant and a compliance audit view
- **AI knowledge base**: RAG on Qdrant with source citations and tenant isolation; model providers are managed as data and can be hot-swapped
### Engineering foundation
- **No controllers**: More than 150 application services are exposed as REST through Dynamic API, with writes in AppServices and reads in QueryServices, documented live in Scalar
- **Architecture rules backed by tests**: Over 2,700 tests, including structural ones that check which database each entity lives in, whether unique indexes include tenant scope, and that no page hard-codes a permission code
- **A foundation you can take with you**: The backend foundation, XiHan.Framework, ships as over 60 independently referenceable NuGet packages and BasicApp uses only public APIs, so you can launch on the template and replace it piece by piece
## Tech Stack
Backend: .NET with XiHan.Framework (SqlSugar, Redis, SignalR, Serilog and Scalar all arrive through the framework). Frontend: Vue + TypeScript + Vite + XiHan.UI + Pinia + Tailwind CSS.
Item-by-item lists live in the [backend](./backend/README.md#dependency-footprint) and [frontend](./frontend/README.md#stack) engineering notes.
## Architecture
Frontend and backend each split into three aligned layers: the app layer holds pages and entry points, the kernel layer holds platform capabilities, and the base layer is the in-house XiHan.UI and XiHan.Framework. Each backend module follows DDD layering internally (Domain / Application / Infrastructure), and the two sides cooperate through Dynamic API, SignalR, and the menus and permission codes the backend publishes.
