v6 Monorepo Architecture
Ray Template v6 puts Ray Admin, the VitePress documentation site, and ten shared packages in one pnpm workspace. Ray Admin owns sign-in, business pages, and application state. The documentation site runs examples from the same component sources. Shared packages expose reusable implementations through public entry points.
Workspace overview
ray-template/
├─ apps/
│ ├─ admin/ Ray Admin
│ │ ├─ index.html Admin entry
│ │ ├─ example.html Demo entry
│ │ └─ src/
│ │ ├─ main.ts Bootstrap
│ │ ├─ App.tsx Providers
│ │ ├─ app-config/ App config
│ │ ├─ app-components/ Host UI
│ │ ├─ locales/ Locales
│ │ ├─ router/ Route guards
│ │ │ └─ config/ Route inputs
│ │ ├─ store/ Pinia state
│ │ │ ├─ modules/ Pinia stores
│ │ │ └─ hooks/ State access
│ │ ├─ layout/ Shell wiring
│ │ ├─ views/ Pages, demos
│ │ ├─ api/ API calls
│ │ │ ├─ admin/ Admin API
│ │ │ └─ demo/ Demo queries
│ │ ├─ axios/ Interceptors
│ │ └─ mocks/ MSW state
│ └─ docs/ VitePress
│ ├─ .vitepress/
│ │ ├─ config.mts Site config
│ │ ├─ sidebar.mts Sidebar
│ │ ├─ legacy.mts Legacy URLs
│ │ └─ theme/ Site theme
│ ├─ guide/ Guides
│ ├─ reference/ API docs
│ ├─ examples/ Vue examples
│ └─ playground/ Layout demo
├─ packages/
│ ├─ admin-shell/ Layout shell
│ ├─ routing/ Navigation
│ ├─ ui/ UI and theme
│ ├─ icons/ SVG icons
│ ├─ http/ HTTP client
│ ├─ api-contracts/ API schemas
│ ├─ demo-data/ Fixtures
│ ├─ composables/ Vue hooks
│ ├─ directives/ Directives
│ └─ utils/ Utilities
├─ harness/ Task checks
└─ pnpm-lock.yaml LockfileRay Admin uses all the shared packages shown above. The docs import the packages needed by each example, including UI, layout, and routing. Examples that need the full admin context open an isolated entry in an iframe. Each application declares dependencies in its own package.json and uses the workspace lockfile. Workspace configuration · Engineering architecture map
The full-stack source also includes apps/server, which runs independently. Server architecture
How Ray Admin is assembled
Bootstrap and global services
index.html → main.ts
↓
Install Pinia and language packs
↓
Restore the session → Set up Vue Router
↓
Install Day.js and directives
↓
Mount App.tsx and global providers
↓
RouterView → Active pageStandalone and Wujie sub-app modes use the same plugin setup. Startup restores the session before deciding whether to load account routes. src/app-config/ supplies theme, route, request, and cache configuration. Bootstrap entry point · Application configuration
App.tsx assembles Naive UI, global styles, the watermark, and loading state. Through @ray-template/ui/services it provides theme, translation, icon URLs, notifications, and column preference storage. Shared UI components consume these through UiServices, so the docs can run them in their own context. App source
From route configuration to menus and pages
Built-in JSON / Local / Remote
↓
router/config/source.ts → Select source
↓
api-contracts → Validate structure
↓
routing + config/views.ts
Bind view IDs to page loaders
↓
Vue Router + App guards
├─→ store/menu → Menus, tabs, crumbs
└─→ RLayout → AdminShell → Pagerouter/registers sign-in, status, and current-account routes. Built-in configuration comes fromdemo-data.router/config/views.tsregisters the loadableviews/pages. Guards use the verified session and route permissions to decide whether to enter a page. Routes, menus, and permissionsstore/keeps state by responsibility.signinghandles sessions.menuderives menus from permissions and syncs tabs and breadcrumbs with the route.keep-alivetracks cacheable pages.settingpersists selected preferences, whileruntimerebuilds loading, drawer, and maximization state on mount. Store hooks expose state and actions. Store referencelayout/adapts the shared shell.RLayoutsupplies layout preferences and slots for navigation and content toAdminShell. The default content slot wires request cancellation and page transitions. The transition uses the cache settings and allowlist to renderKeepAlive. Layout and state
The path of a business request
views/ or store/
↓
api/admin/ or api/demo/
↓
axios/ App interceptors
↓
@ray-template/http Axios instance
├─→ MSW → mocks/ → Demo fixtures
└─→ HTTP → Configured APIapi/ wraps endpoints. The admin client adds session transport and validates responses with api-contracts. axios/ configures request, response, and error interceptors. http provides a canceler for each instance and accepts a caller-provided AbortSignal. Requests, cancellation, and mocks
Development and the static hosted demo can use the same MSW HTTP mock. mocks/handlers.ts implements endpoints. mocks/database.ts handles demo sessions, users, and route reads and writes. demo-data provides initial fixtures and query utilities. When a real API is connected, the server verifies sessions and authorizes resource access. Backend integration and the standard API contract
How the docs run components
Documentation page
├─ Render examples/*.vue directly
│ └─ Public entry, e.g. ui/table-pro
└─ Embed through AdminExample.vue
└─ admin/example.html
└─ documentation-example.tsx
└─ Allowed admin demo routes- Direct examples. The precision, barcode, and TablePro examples import shared packages. Markdown includes the same
.vuefile used by the runnable example. TablePro receives local rows or a cancelable mock query. The layout playground has a separate preview page and in-memory router. Precision arithmetic · Barcode · TablePro example · Live layout playground - Embedded admin demos.
AdminExample.vuehosts examples that need the admin layout or application context.example.htmluses its own bootstrap, restricted example routes, and Pinia instance. Ordinary app cache is in memory, and column visibility uses a separate session storage namespace. Docs source overview
Optional backend layers
apps/server/src/main.ts starts a standalone NestJS HTTP service. app.ts installs the business modules, platform middleware, global response interceptor, and exception filter.
Browser request to /api
↓
platform/ ─────────→ Redis
↓ Limits, demo cache
NestJS guards and controllers
├─ auth / users / routes
│ └─ Prisma → PostgreSQL
└─ demo (when enabled)
└─ @ray-template/demo-datamodules/auth/handles authentication and sessions and installs the global authorization guard.modules/users/handles account management and provides department and role options.modules/routes/reads, filters, and saves route configuration. Business modules define and validate HTTP data withapi-contracts.infrastructure/database.tswraps Prisma access. The schema and migrations underprisma/define users, credentials, grants, sessions, route configuration, and audit records in PostgreSQL. The database is authoritative for sessions and permissions.platform/owns Redis, request IDs, logs, security middleware, and health checks. Redis provides rate limits and caches selected reconstructible demo reads. Demo endpoints are enabled by deployment configuration and sharedemo-data.
apps/server builds independently and ships in the full-stack source distribution. Server source overview · Source distributions and startup
Shared package responsibilities
Arrows show direct dependencies from the importing shared package to the package it uses. Names in the diagram stand for @ray-template/<name>.
admin-shell
├─→ ui ───────┬─→ composables
│ ├─→ icons
│ └─→ utils
├─→ routing ──┬─→ api-contracts
│ ├─→ icons
│ └─→ utils
├─→ composables
└─→ icons
directives ──┬─→ composables
└─→ utils
composables ───→ utils
http ──────────→ utils
demo-data ─────→ api-contractspackage.json#exports declares public entry points. Prefer feature imports across workspaces, for example @ray-template/ui/table-pro or @ray-template/utils/precision. rayTemplate.runtime distinguishes browser, server, and universal. api-contracts and demo-data are universal and can be used by the browser and server. Universal workspaces depend only on other universal workspaces. Applications consume public package entries to assemble features. pnpm packages:check validates workspace dependencies, public entries, and cycles. Package boundary check
UI, layout, and routing
@ray-template/admin-shellimplements layout modes and slot placement inAdminShell.tsx.TopNavigation.tsx,ShellTab.tsx, andmenu-keyboard.tssupport navigation, tabs, and keyboard interaction.LayoutSettings.tsxprovides layout options andRouteTransition.vuehandles transitions and cache rendering. The host supplies layout state, menu items, navigation actions, and content. Shell exports@ray-template/routingexposes/contractto bind host-provided views, reserved paths, and permission rules to serializable config and Vue Router records. It supports exporting records back to JSON./expand-routes,/order-routes, and/navigationexpand and order routes and traverse menu trees./schemaand/json-schemaare compatibility exports backed byapi-contracts. Routing exports@ray-template/uiorganizes implementations, types, and styles by component, with entries such as/table-pro,/form,/chart, and/barcode./theme.cssand/theme-presetssupply design variables and presets./servicesconnects host themes, translations, notifications, and storage to components. Component reference@ray-template/iconsgroups SVG sources by directory. The generated/manifestprovides full icon names, types, and group asset URLs. The admin build generates a sprite per group.RIconand route configuration use the same names, such asnavigation/table. SVG icons
In TablePro, TablePro.tsx composes filtering, pagination, queries, and the instance API. useTableSearch manages drafts and submitted filters. useTableRequest handles remote request status and cancellation. TablePanel owns the Naive UI data table, column settings, and tools. The host supplies the query and column preference storage. TablePro reference · Component entry point
Submit search / Change page
↓
TablePro → useTableRequest
↓
Host request(params, signal)
↓
Current page data + Filtered total
↓
TablePanel → Naive UI NDataTableHTTP, contracts, and demo data
@ray-template/httpexposescreateHttpClientinclient.tsto create an independent Axios instance that returns HTTP response bodies.RequestCancelertracks and clears pending requests. The host chooses the base URL, headers, and interceptors. HTTP client source@ray-template/api-contractsdefines envelopes, sessions, and admin models under/adminand demo queries and responses under/demo.routes.tsis the route schema source./route-validationvalidates structure, and/route-json-schemaand/openapigenerate editor and API integration descriptions. Frontend, mock, and server consumers share the Valibot contracts. API contract package@ray-template/demo-dataincludes default routes inroutes.json, initial options, charts, orders, people, and helpers for search, filtering, and pagination. Hosts decide when to enable demos and manage their own sessions and writes. Demo data package
Hooks, directives, and utilities
@ray-template/composablesoffers Vue lifecycle and element-reference helpers under/vue. Feature hooks have their own entries, including/useDevice,/useElementFullscreen,/useDomToImage, and/usePrint. Admin-specific navigation, layout, and state hooks live underapps/admin/src/hooks/template/. Hooks reference@ray-template/directiveskeeps implementations and types by directive undersrc/modules/. Import entries such as/copy,/debounce, and/throttleas needed. Ray Admin'ssrc/directives/index.tsregisters the directives it uses. Directives reference@ray-template/utilsprovides precision arithmetic via/precisionand object, file, and type helpers via/core,/files, and/types./storagereads and writes namespaced JSON through a host-supplied store. The host chooses the storage location and cache keys. Utilities reference
Build and deploy
pnpm dev starts Admin and pnpm docs:dev starts the docs. pnpm build builds Admin, pnpm docs:build builds the docs, and pnpm pages:build assembles them under dist/pages. The hosted application is at /ray-template/ and the docs are at /ray-template/docs/, with English at /ray-template/docs/en/. Build and deployment guide
For a project based on v5, review the compatibility boundaries and adoption process. Moving from v5 to v6