monisuo/monisuo-admin/.agents/skills/shadcn-vue-admin/references/SYSTEM_KNOWLEDGE_MAP.md

System Knowledge Map (for agents)

This is a “navigation index”. It only keeps the high-level structure and key entry files so AI can locate things quickly.

Project Overview

• Stack: Vue 3 + Vite + TypeScript + TailwindCSS
• Routing: vue-router (v5+ with automatic routes from src/pages) + vite-plugin-vue-layouts
• State: Pinia (with persistedstate)
• Data: Axios + @tanstack/vue-query
• Forms: vee-validate + zod
• UI: shadcn-vue / reka-ui / lucide-vue-next / vue-sonner

Startup Flow

• index.html
• src/main.ts: creates the app, registers plugins, imports global CSS, loads src/utils/env
• src/App.vue: <router-view /> + <Suspense>, initializes useSystemTheme()

Build / Generation (Vite)

• vite.config.ts
  • Alias: @ -> src/
  • Route generation: vue-router/vite (types: src/types/route-map.d.ts)
  • Layouts: vite-plugin-vue-layouts (default: default)
  • Auto-import: src/composables / src/constants / src/stores (types: src/types/auto-import.d.ts)
  • Components: src/components (types: src/types/auto-import-components.d.ts)

Routing & Layouts

• Pages (route source): src/pages/**
• Router (assembly / scroll behavior / HMR): src/router/index.ts
• Guards: src/router/guard/* (includes auth + nprogress)
• Layouts: src/layouts/*.vue (default / blank / marketing)

In page files you can use <route lang="yaml"> to define meta (commonly: layout/auth). Example YAML:

meta:
  # layout can be: false | blank | marketing
  layout: blank
  auth: true

State & Theme

• Stores: src/stores/* (auth.ts, theme.ts)
• Theme: src/composables/use-system-theme.ts + src/assets/themes.css
• Dark/Light/System: src/components/toggle-theme.vue

Data Fetching / API

• Axios: src/composables/use-axios.ts
• Vue Query plugin: src/plugins/tanstack-vue-query/setup.ts
• API modules: src/services/api/*.api.ts
• Shared response types: src/services/types/response.type.ts

Environment Variables

When adding environment variables, make sure to validate/types them in src/utils/env.ts.

Third-party Plugin Setup

Plugin initialization entry: src/plugins/index.ts

1. When introducing a third-party plugin that needs configuration, put the setup in src/plugins/[plugin-name]/setup.ts.
2. Import/register it from src/plugins/index.ts.

Form Validation

• Validators: src/pages/**/validators/*.validator.ts (zod)
• Forms: src/pages/**/components/*-form.vue (commonly: toTypedSchema + useForm)

UI Component Directories

• Base UI: src/components/ui/**
• Layout components: src/components/global-layout/**
• Sidebar: src/components/app-sidebar/**
• Command palette: src/components/command-menu-panel/**

Page / Module Directory Convention

Routes are generated automatically from the file structure.

• Pages: src/pages/**/*.vue
• Page components: src/pages/**/components/**/*.vue
• Validators: src/pages/**/validators/*.validator.ts
• For data-display pages, table configuration should live in: src/pages/**/data/**

Key Conventions

• Routing is file-based: do NOT hand-edit route tables; add/rename/remove pages under src/pages/**.
• Prefer <route lang="yaml"> meta over ad-hoc logic (commonly: meta.layout, meta.auth).
• Keep env vars strictly typed/validated in src/utils/env.ts before use.
• Prefer @/ (alias to src/) imports to avoid brittle relative paths.

Common Tasks (Where to Change)

• Add a new page/route: create src/pages/<name>.vue (or src/pages/<name>/index.vue) + optional <route lang="yaml"> meta.
• Add/modify a layout: edit src/layouts/*.vue, then set meta.layout in the page.
• Add a plugin: create src/plugins/<plugin>/setup.ts, then register it in src/plugins/index.ts.
• Add an API module: create src/services/api/*.api.ts; put shared request/response types in src/services/types/* or src/services/api/types/*.
• Add data fetching: use Axios (src/composables/use-axios.ts) + Vue Query (setup: src/plugins/tanstack-vue-query/setup.ts).
• Add a form: define a zod validator in src/pages/**/validators/*.validator.ts, then use it from src/pages/**/components/*-form.vue.
• Add a store: create src/stores/*.ts (Pinia; persistedstate is enabled).

Common Pitfalls

• Auto-generated types/routes: when pages change, TypeScript/IDE may need a restart to pick up updated generated types (e.g. src/types/route-map.d.ts).
• Auto-imported symbols: composables/constants/stores are auto-imported; name collisions can silently change which symbol you get.
• Layout meta values: ensure meta.layout matches an actual layout filename (and understand what layout: false does in this project).
• Env vars: Vite uses import.meta.env; do not bypass src/utils/env.ts validation.

Quick Verification

• Dev: pnpm dev
• Lint: pnpm lint:fix
• Build: pnpm build