ray-template/docs/architecture.md

13 KiB

Architecture map

Ray Template is a pnpm workspace. The admin application owns host integration, the documentation site explains public usage, and shared packages own reusable implementations. Use the task index to locate features. Use this page to identify ownership and trace calls across modules.

Workspaces

Directory Responsibility and authoritative entry point
apps/admin Ray Admin: application configuration, route registration, Pinia, providers, pages, demo data, and development mocks. This is Vite's application root.
apps/docs VitePress site: reader guides, APIs, migration instructions, and interactive examples consuming public shared-package entry points.
packages Shared packages listed below. Each package's package.json#exports defines its root entry point and importable subpaths.
Tests Vitest regressions grouped by behavior rather than mirroring the source tree. Use Harness scopes to locate coverage.
docs, harness Maintainer conventions and cross-module explanations. Harness owns task navigation, targeted checks, and evidence. Reader-facing documentation belongs in apps/docs.
scripts, vite-helper, unplugin Repository checks, Vite plugin helpers, and generated auto-import declarations. Build, type, and CI configuration remains at the root.
Shared package Implementation ownership Host boundary
@ray-template/utils Precision, type checks, data/file utilities, and generic JSON storage Callers supply Storage. Application keys, cache backends, and legacy AES formats stay in the application.
@ray-template/composables Vue composables and DOM, element, and scope utilities Application-specific navigation, theme, and content-area hooks stay in the application.
@ray-template/directives Vue directives and registration The host supplies copy notifications and decides when to register.
@ray-template/icons SVG files, manifests, icon-name types, and lookups The build generates spritemaps. The host supplies icon-resolution services.
@ray-template/ui Shared components, themes, and UI service interfaces The admin application injects translation, theme, storage, and other services. Application component entry points re-export shared components.
@ray-template/http Independent HTTP clients, interceptors, and cancellation The application supplies request configuration and interceptors, and wraps business APIs.
@ray-template/api-contracts Business/demo API types, runtime schemas, and OpenAPI Independent of browsers and mocks. The application, mocks, and integrating backends share the protocol.
@ray-template/routing Route configuration validation, expansion, and menu traversal The application owns the view registry, configuration sources, roles, sessions, and guards.
@ray-template/admin-shell Layout shell, settings, transitions, and cached-page rendering The host supplies route state, preferences, navigation, and content slots.

Application @/components, @/hooks, and @/utils include compatibility entry points. Follow actual exports to determine ownership. Shared packages must not depend on application aliases or relative imports across workspaces. The package-boundary check validates dependency declarations, public entry points, and cycles.

Key runtime flows

Flow Call order and boundaries Continue with
Admin bootstrap index.html → main.ts → Pinia → internationalization → Router → Day.js → directives and autocomplete settings → mount App.tsx. Standalone and Wujie modes share plugin registration order. Layout and bootstrap
Navigation and caching Router initialization loads the source → application route modules expand configuration → guards and pages are registered → application menu stores and layouts consume routes. The application maintains the cache allowlist; the shared shell renders transitions and KeepAlive. Routing, layout
Requests and demo data API → application Axios instance → shared client. Development and static online demos share HTTP mocks. Users, sessions, and routes are read/written through APIs; integrating backends own real sessions and resource authorization. API
Documentation examples Documentation can consume shared packages directly. When application context is required, AdminExample.vue embeds example.html with isolated bootstrap, restricted routes, and in-memory caching. Documentation and examples
Application configuration Vite injects __APP_CFG__ and __DEV__; application configuration is grouped by design, requests, routing, and caching. Build and toolchain

After a successful development mount, application doctor reports configuration warnings independently of startup failures. It does not initialize services or impose a business home route.

Maintain guides and runnable examples for public behavior changes through application/documentation coordination. See visual and layout guidance for page design and comment style for code comments.

TypeScript project configuration

The root configuration references four projects. Strict mode, module resolution, and type-checking aliases live in the shared configuration. When changing aliases, check Vite and Vitest as well.

Configuration Coverage
Application Admin apps/admin/src, Vue JSX, and generated declarations.
Node Root build/test configuration, vite-helper, and build helpers.
Tests __test__ and referenced source, loading Vitest and Node types. Vitest configuration and individual test files determine the runtime environment.
Shared packages packages/*/src, without inheriting application aliases or auto-import declarations.
Documentation site Independent documentation-example checks, run by pnpm docs:check.

pnpm typecheck first validates icon synchronization, then runs vue-tsc --build for the four projects referenced by the root configuration. Incremental caches live in node_modules/.cache/ray-template/. Use pnpm exec vue-tsc -p <configuration-file> for an individual project.

Deployment and search discovery

pnpm build produces admin output in dist/production; pnpm docs:build produces apps/docs/.vitepress/dist. pnpm pages:build combines them in dist/pages, with documentation under docs/. The default admin base is /ray-template/; the documentation base is /ray-template/docs/. For root hosting or another subpath, align the admin base, documentation base, and legacy redirect targets.

After main-branch checks pass, CI publishes the combined output to the dist branch. The admin public .nojekyll file is copied into the output. Preserve it when deploying manually to Pages so assets with underscore prefixes can load.

For public builds, set RAY_TEMPLATE_SITE_ORIGIN to the actual site origin; the base supplies the path. Without it, admin production builds emit noindex. The public admin landing page generates canonical metadata, sharing previews, and sitemap.xml; authenticated hash routes are not listed as public pages. Domain-level crawling rules belong in /robots.txt at the site root. VitePress mappings generate legacy in-site links. When a site origin is configured, the assembly script also generates dist/legacy-docs for migrating the old site.

Establish implementation behavior from tracked source and configuration. Generated artifacts, dependencies, caches, and .harness-local/ reports are useful for inspecting build and verification results.