Add the NestJS backend with PostgreSQL and Redis, local setup, and independent frontend and fullstack source archives. Enforce permissions across redirects, let users dismiss the 403 page, and restore missing translation warnings in development.
16 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, route contracts, and OpenAPI | Independent of browsers and mocks. The application, mocks, and integrating backends share the protocol. |
| @ray-template/demo-data | Runtime-neutral fixtures, initial route data, and demonstration query helpers | Mock and optional backend consumers decide when demonstration behavior is enabled. |
| @ray-template/routing | Browser route expansion, menu traversal, and compatibility schema exports | 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. Each workspace declares rayTemplate.runtime as browser, server, or universal: applications cannot be dependencies; universal packages depend only on universal packages; browser/server workspaces cannot import each other. The canonical route schemas and structural validation live in packages/api-contracts; packages/routing retains compatibility exports and browser view binding. packages/demo-data/src/routes.json owns the initial route fixture.
Source distributions
The distribution exporter creates source directories and .tar.gz archives under dist/distributions. The frontend edition retains Admin, Docs, and their reachable workspace dependencies, with a pruned lockfile and usable scripts. distribution.json records the edition, version, source commit/worktree state, workspace set, file count, and content digest. Explicit source inputs exclude local credentials, dependencies, generated builds, and verification evidence.
Markdown blocks delimited by the HTML comment markers fullstack:start and fullstack:end are removed from frontend exports. Keep references to omitted server files inside these blocks. Export is local only; branch/Release publication is a separate integration step. Read the distribution guide for user commands.
Optional server workspace
apps/server owns NestJS controllers/services, PostgreSQL persistence through Prisma, migrations, credential initialization, authorization, and audit records. It consumes only universal workspace packages and keeps ORM models out of browser contracts. Platform infrastructure owns Redis rate limits/cache, request IDs and redacted JSON logs, security headers, CORS, health probes, and resource shutdown. Database sessions and authorization are never cached.
The fullstack launcher creates private local configuration once, starts PostgreSQL/Redis through Compose, migrates/seeds without resetting existing accounts, and waits for backend readiness before starting Vite with a same-origin API proxy. External databases are supported through setup --external. Fullstack source export adds this workspace and its deployment configuration. Docker and production deployment require independent runtime acceptance.
The server has its own TypeScript configuration and build output. Tests under apps/server/test use Node's test runner; database integration tests require explicit test PostgreSQL and Redis URLs. Frontend builds do not initialize server resources.
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. |
| Universal contracts/data | Node-only type-checking environment for API contracts and demo data; no browser DOM library. |
| 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.