CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

This project uses cnpm as the package manager (not npm or yarn).

Development:

cnpm run dev          # Start dev server on port 5173

Building:

cnpm run build        # Production build (uses 8GB memory allocation)

Type Checking:

cnpm run type-check   # Run TypeScript type checking without emitting files

Preview:

cnpm run preview      # Preview production build locally

Tech Stack

• Frontend Framework: Vue 3 with Composition API
• Language: TypeScript
• Build Tool: Vite 6
• State Management: Pinia (Composition API style with defineStore)
• Routing: Vue Router 4 with hash history mode
• UI Components: Element Plus (with auto-import)
• Internationalization: vue-i18n
• Rich Text Editors: Multiple options (BlockSuite, Univer.js, Cherry Markdown, Vditor)
• Auto-imports: Vue, Vue Router, Pinia, vue-i18n APIs are auto-imported (see auto-imports.d.ts)

Project Structure

src/
├── api/              # API service modules (user, chat, files, etc.)
├── assets/           # Static assets (styles, images)
├── components/       # Reusable Vue components organized by feature
│   ├── auth/         # Authentication components
│   ├── Chat/         # Chat-related components
│   ├── KnowledgeBase/
│   ├── Settings/
│   ├── Workspace/
│   └── common/       # Shared components
├── layout/           # Layout components (MainLayout, etc.)
├── locales/          # i18n translation files
├── pages/            # Top-level page components (Auth, Welcome, Workspace, etc.)
├── router/           # Vue Router configuration
├── stores/           # Pinia stores (auth, user, chat, settings, etc.)
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
├── App.vue           # Root component
└── main.ts           # Application entry point

Architecture Overview

State Management (Pinia)

All stores use the Composition API style with defineStore:

• State is defined using ref() or reactive()
• Getters use computed()
• Actions are plain functions
• Store files are in src/stores/

Example store pattern:

export const useAuthStore = defineStore('auth', () => {
  const token = ref<string>('')
  const isAuthenticated = computed(() => !!token.value)

  async function login(credentials) {
    // action logic
  }

  return { token, isAuthenticated, login }
})

API Layer

API services are organized by domain in src/api/:

• Each service exports functions that make HTTP requests
• Uses axios via src/utils/request.ts (configured as service)
• Mock API interceptors available in src/api/mock.ts for development

Routing

• Uses hash history mode (createWebHashHistory())
• Main layout at /app with nested routes
• Route meta includes:
  • requiresAuth: boolean for auth guard
  • hideIntelligencePanel: control panel visibility
  • title, icon, hidden: UI metadata
• Global navigation guards in src/router/index.ts:
  • Token-based authentication on /auth?token=...
  • Redirect unauthenticated users to login

Components Organization

Components are organized by feature:

• Feature folders (Chat, KnowledgeBase, Settings, Workspace, auth): Domain-specific components
• common/: Shared components used across features
• layout/: Application layout components

Auto-imports

The project uses unplugin-auto-import and unplugin-vue-components:

• Vue APIs (ref, computed, watch, etc.) are auto-imported
• Vue Router APIs (useRouter, useRoute) are auto-imported
• Pinia APIs (storeToRefs, etc.) are auto-imported
• vue-i18n APIs are auto-imported
• Element Plus components are auto-imported
• Type definitions regenerated in dev mode: src/auto-import.d.ts and src/components.d.ts

Environment Configuration

Environment variables are defined in vite.config.ts (not in .env files):

• import.meta.env.VITE_APP_BASE_URL: API base URL (defaults to https://ai.linkmed.cc)
• Dev server proxies /api and /deepresearch to the backend

Build System Notes

The Vite configuration includes several custom plugins to handle module compatibility issues:

1. fixModuleNotDefined: Handles CJS modules in development mode
2. fixProblematicCjsModules: Fixes specific problematic CJS modules (lodash, file-saver, etc.)
3. fixBlockSuiteAccessor: Transforms modern accessor syntax in BlockSuite packages during build
4. fixHighlightJs: Fixes highlight.js import issues

These plugins exist because the project uses many complex dependencies (BlockSuite, Univer.js, React-based libraries) that have CJS/ESM compatibility issues.

Important build configuration:

• Build target is es2022 (for better class/decorator handling)
• Memory allocation increased to 8GB for production builds
• Manual chunk splitting for optimal bundle size
• React dependencies are included despite this being a Vue project (required by BlockSuite)

Development Guidelines

Adding New Features

1. Create a new store in src/stores/ if state management is needed
2. Add API functions in appropriate src/api/ module
3. Create feature-specific components in src/components/[feature]/
4. Add page components in src/pages/ if needed
5. Update routes in src/router/index.ts

Working with API

The backend base URL is proxied in development:

• Local API calls use /api prefix (proxied to backend)
• Backend base URL: https://ai.linkmed.cc (can be changed in vite.config.ts line 206)

Type Safety

• TypeScript strict mode is enabled
• Use the auto-generated type definitions in src/auto-import.d.ts and src/components.d.ts
• Type definitions for custom modules in src/types/

Authentication Flow

1. User logs in via /auth route
2. Token stored in localStorage (key: auth_token)
3. Auth state managed by useAuthStore (src/stores/auth.ts)
4. Token refresh logic included
5. Router guard checks isAuthenticated computed property

Common Issues

Module Resolution Errors

If you encounter "module is not defined" or CJS/ESM errors:

• Check if the module needs to be added to fixProblematicCjsModules in vite.config.ts
• Consider adding to resolve.dedupe array if there are version conflicts

Build Memory Issues

If build fails with JavaScript heap out of memory:

• Memory is already allocated to 8GB in package.json build script
• If needed, increase further in the NODE_OPTIONS=--max-old-space-size=XXXX flag

BlockSuite/Univer Integration

These are complex dependencies with special requirements:

• Do not modify their import patterns
• They require React as a peer dependency
• Custom esbuild configuration is needed for decorators