From 7e6a087049444b0d2c5f0238fc2b40d118165469 Mon Sep 17 00:00:00 2001
From: mrholek <lukasz@holeczek.pl>
Date: Wed, 1 Apr 2026 10:47:02 +0200
Subject: [PATCH] docs: add AI-friendly documentation and code comments

Add comprehensive documentation for AI assistants:
- .cursorrules with project context and conventions
- ARCHITECTURE.md with technical details
- DEVELOPMENT.md with practical guides
- JSDoc comments in all JavaScript modules
- Update README.md with AI-Friendly Development section

This enables AI tools (Cursor, Claude Code, GitHub Copilot) to understand the project and generate code following CoreUI Vue patterns.
---
 .cursorrules        |  349 ++++++++++++++
 ARCHITECTURE.md     |  716 ++++++++++++++++++++++++++++
 DEVELOPMENT.md      | 1113 +++++++++++++++++++++++++++++++++++++++++++
 README.md           |   40 +-
 src/App.vue         |   14 +
 src/_nav.js         |   23 +
 src/main.js         |   34 +-
 src/router/index.js |   28 ++
 8 files changed, 2313 insertions(+), 4 deletions(-)
 create mode 100644 .cursorrules
 create mode 100644 ARCHITECTURE.md
 create mode 100644 DEVELOPMENT.md

diff --git a/.cursorrules b/.cursorrules
new file mode 100644
index 00000000..fc27ae53
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1,349 @@
+# CoreUI Free Vue Admin Template - AI Assistant Rules
+
+You are working with the CoreUI Free Vue Admin Template, a professional admin dashboard built with Vue 3, CoreUI Vue components, and modern build tools. This project uses Vite for development and building, Vue Router for navigation, Pinia for state management, and Sass for styling.
+
+## Critical Rules
+
+**Component Library**: ALWAYS use CoreUI Vue components from https://coreui.io/vue/docs/. NEVER use Tailwind CSS, Vuetify, Element Plus, or other component libraries. This project is built on Bootstrap 5 and CoreUI Vue components exclusively.
+
+**Technology Stack**: This project uses:
+- Vue 3.5.x with Composition API and script setup
+- Single File Components (SFC) with <template>, <script>, and <style> sections
+- CoreUI Vue 5.x and @coreui/coreui 5.x
+- Vue Router 5.x for client-side routing
+- Pinia 3.x for state management
+- Vite 8.x for development server and building
+- Sass/SCSS for styling with Bootstrap 5 variables
+- Chart.js 4.x with @coreui/vue-chartjs for data visualization
+
+## Code Conventions
+
+**Vue/JavaScript Standards**:
+- Use Composition API with `<script setup>` syntax
+- Use ref() and reactive() for reactive state
+- Follow Vue 3 Composition API patterns
+- Use Prettier formatting: no semicolons, single quotes, 2-space indentation
+- Enforce ESLint rules with Vue and Prettier plugins
+- Prefer const and arrow functions
+- Use destructuring where appropriate
+
+**File Organization**:
+- `src/` - All source code
+  - `components/` - Reusable UI components (AppHeader, AppSidebar, etc.)
+  - `views/` - Page components organized by feature (dashboard, forms, charts, etc.)
+  - `layouts/` - Layout wrapper components (DefaultLayout)
+  - `assets/` - Static assets (images, brand logos)
+  - `scss/` - Global styles and theme customization
+  - `router/` - Router configuration
+  - `stores/` - Pinia stores
+  - `_nav.js` - Navigation/sidebar menu configuration
+  - `App.vue` - Main application component
+  - `main.js` - Application entry point
+
+**Vue/SFC Practices**:
+- Use `<script setup>` for components (preferred modern syntax)
+- Use `defineProps()` and `defineEmits()` for component API
+- Use computed() for derived state
+- Use watch() or watchEffect() for side effects
+- Keep components focused and single-responsibility
+- Extract reusable logic into composables (useX pattern)
+- Use Suspense for async components when needed
+
+**CSS/Sass Practices**:
+- Import global styles in main.js: `import './scss/style.scss'`
+- Use Bootstrap utilities first before custom CSS
+- Leverage CoreUI CSS custom properties for theming
+- Support dark mode through CoreUI's color mode system
+- File: `src/scss/style.scss` - main stylesheet importing CoreUI and Bootstrap
+- File: `src/scss/_custom.scss` - custom style overrides
+- Use scoped styles in components: `<style scoped>`
+- Use SCSS variables from Bootstrap and CoreUI when possible
+
+**Routing Conventions**:
+- Use createWebHashHistory for client-side routing (GitHub Pages compatible)
+- Define routes in router/index.js as array of objects
+- Use dynamic imports for lazy loading route components
+- Use exact path matching where needed
+- Public routes (login, register, 404, 500) defined separately
+- Protected routes handled in DefaultLayout
+
+**State Management**:
+- Use Pinia for global state (theme, sidebar visibility)
+- Create stores in stores/ directory
+- Use defineStore() with setup syntax
+- Access stores with const store = useStore()
+- Keep component-level state in ref() or reactive() when state is local
+
+**Naming Conventions**:
+- PascalCase for component files and component names (AppHeader.vue, DefaultLayout.vue)
+- camelCase for variables, functions, and composables (useState, useEffect)
+- UPPER_SNAKE_CASE for constants (API_URL, MAX_ITEMS)
+- kebab-case for CSS classes (following Bootstrap/CoreUI conventions)
+- Descriptive names that indicate purpose (AppHeaderDropdown vs Dropdown)
+
+## Project Structure
+
+```
+coreui-free-vue-admin-template/
+├── public/              # Static assets served directly
+├── src/
+│   ├── assets/         # Images, logos, icons
+│   │   ├── brand/     # Logo components
+│   │   └── images/    # Image files
+│   ├── components/     # Reusable UI components
+│   │   ├── AppHeader.vue
+│   │   ├── AppSidebar.vue
+│   │   ├── AppFooter.vue
+│   │   ├── AppContent.vue
+│   │   ├── AppBreadcrumb.vue
+│   │   └── AppHeaderDropdown.vue
+│   ├── layouts/        # Layout components
+│   │   └── DefaultLayout.vue
+│   ├── views/          # Page components
+│   │   ├── dashboard/ # Dashboard page
+│   │   ├── base/      # Base UI components examples
+│   │   ├── buttons/   # Button examples
+│   │   ├── forms/     # Form examples
+│   │   ├── charts/    # Chart examples
+│   │   ├── icons/     # Icon examples
+│   │   ├── notifications/ # Notification examples
+│   │   ├── widgets/   # Widget examples
+│   │   └── pages/     # Auth & error pages
+│   ├── router/         # Router configuration
+│   │   └── index.js   # Route definitions
+│   ├── stores/         # Pinia stores
+│   ├── scss/           # Stylesheets
+│   │   ├── style.scss # Main stylesheet
+│   │   └── _custom.scss # Custom overrides
+│   ├── App.vue         # Main app component
+│   ├── main.js         # Entry point
+│   └── _nav.js         # Navigation config
+├── index.html          # HTML template
+├── vite.config.mjs     # Vite configuration
+├── eslint.config.mjs   # ESLint configuration
+├── package.json        # Dependencies
+└── README.md           # Documentation
+```
+
+## Development Workflow
+
+**Starting Development**:
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server (http://localhost:3000)
+npm run build        # Build for production
+npm run preview      # Preview production build
+npm run lint         # Run ESLint
+```
+
+**Adding a New Page**:
+1. Create component in `src/views/[feature]/ComponentName.vue`
+2. Add route to `src/router/index.js`
+3. Add navigation item to `src/_nav.js` (if needed)
+4. Import and use CoreUI components from '@coreui/vue'
+
+**Creating Components**:
+```vue
+<template>
+  <CCard>
+    <CCardHeader>{{ title }}</CCardHeader>
+    <CCardBody>
+      <slot />
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+defineProps({
+  title: {
+    type: String,
+    required: true,
+  },
+})
+</script>
+
+<style scoped>
+/* Component-specific styles */
+</style>
+```
+
+**Using Composition API**:
+```vue
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+import { useStore } from '@/stores/main'
+
+const data = ref([])
+const store = useStore()
+const router = useRouter()
+
+const filteredData = computed(() => {
+  return data.value.filter(item => item.active)
+})
+
+watch(data, (newValue) => {
+  console.log('Data changed:', newValue)
+})
+
+onMounted(() => {
+  // Fetch data or run initialization
+})
+
+const navigate = () => {
+  router.push('/dashboard')
+}
+</script>
+```
+
+## Code Quality
+
+**Linting**:
+- ESLint configuration in `eslint.config.mjs`
+- Prettier integration for code formatting
+- Vue-specific rules with eslint-plugin-vue
+- Run `npm run lint` before committing
+
+**Best Practices**:
+- Always define props with types and validation
+- Use meaningful component and variable names
+- Keep components small and focused
+- Extract complex logic into composables
+- Use Vue DevTools for debugging
+- Test in both light and dark themes
+- Ensure responsive design works on all screen sizes
+
+**Git Commits**:
+Follow conventional commit format:
+- feat: New feature
+- fix: Bug fix
+- docs: Documentation changes
+- style: Code style changes (formatting)
+- refactor: Code refactoring
+- test: Adding tests
+- chore: Maintenance tasks
+
+## Common Patterns
+
+**Lazy Loading Routes**:
+```javascript
+const Dashboard = () => import('./views/dashboard/Dashboard.vue')
+```
+
+**Composables** (Custom hooks):
+```javascript
+// composables/useFetch.js
+import { ref } from 'vue'
+
+export function useFetch(url) {
+  const data = ref(null)
+  const error = ref(null)
+  const loading = ref(true)
+
+  fetch(url)
+    .then(res => res.json())
+    .then(json => {
+      data.value = json
+    })
+    .catch(err => {
+      error.value = err
+    })
+    .finally(() => {
+      loading.value = false
+    })
+
+  return { data, error, loading }
+}
+```
+
+**Pinia Store**:
+```javascript
+// stores/main.js
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+export const useStore = defineStore('main', () => {
+  const sidebarVisible = ref(true)
+  const theme = ref('light')
+
+  function toggleSidebar() {
+    sidebarVisible.value = !sidebarVisible.value
+  }
+
+  function setTheme(newTheme) {
+    theme.value = newTheme
+  }
+
+  return { sidebarVisible, theme, toggleSidebar, setTheme }
+})
+```
+
+**Navigation Configuration** (`_nav.js`):
+```javascript
+export default [
+  {
+    component: 'CNavItem',
+    name: 'Dashboard',
+    to: '/dashboard',
+    icon: 'cil-speedometer',
+  },
+]
+```
+
+## AI Assistant Guidelines
+
+**What AI Should Do**:
+- Generate code using CoreUI Vue components
+- Follow existing code style and conventions
+- Use Composition API with <script setup>
+- Implement responsive designs
+- Define props with proper validation
+- Follow the project's file organization
+- Use existing utility functions and helpers
+- Suggest performance optimizations when appropriate
+
+**What AI Should NOT Do**:
+- Use Options API (use Composition API instead)
+- Import components from libraries other than CoreUI/Vue
+- Suggest Tailwind CSS or other CSS frameworks
+- Ignore ESLint/Prettier rules
+- Create files outside the src/ directory structure
+- Modify build configuration without clear reason
+- Use deprecated Vue patterns
+
+## External Dependencies
+
+**Core Libraries**:
+- @coreui/coreui: ^5.6.1 - CoreUI CSS framework
+- @coreui/vue: ^5.8.0 - CoreUI Vue components
+- @coreui/icons-vue: 2.2.0 - CoreUI icons for Vue
+- vue: ^3.5.31 - Vue framework
+- vue-router: ^5.0.4 - Routing library
+- pinia: ^3.0.4 - State management
+
+**Additional Libraries**:
+- chart.js: ^4.5.1 - Charting library
+- @coreui/vue-chartjs: ^3.0.0 - CoreUI Chart.js wrapper for Vue
+- simplebar-vue: ^2.4.2 - Custom scrollbars
+- @coreui/utils: ^2.0.2 - Utility functions
+
+## Browser Support
+
+Modern browsers with ES6+ support:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Resources
+
+- CoreUI Vue Documentation: https://coreui.io/vue/docs/
+- CoreUI Components: https://coreui.io/vue/docs/components/
+- Vue 3 Documentation: https://vuejs.org/
+- Vue Router: https://router.vuejs.org/
+- Pinia: https://pinia.vuejs.org/
+- Vite: https://vitejs.dev/
+
+---
+
+Remember: This is a Vue 3 application using CoreUI Vue components. Always check CoreUI Vue documentation for component APIs and usage examples. Keep the code clean, maintainable, and following Vue 3 best practices with Composition API.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 00000000..e4fd16b0
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,716 @@
+# CoreUI Free Vue Admin Template - Architecture
+
+This document provides a comprehensive overview of the CoreUI Free Vue Admin Template architecture, design patterns, and technical implementation details.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Technology Stack](#technology-stack)
+- [Architectural Pattern](#architectural-pattern)
+- [Directory Structure](#directory-structure)
+- [Core Components](#core-components)
+- [Routing System](#routing-system)
+- [State Management](#state-management)
+- [Styling Architecture](#styling-architecture)
+- [Build System](#build-system)
+- [Performance Optimizations](#performance-optimizations)
+- [Browser Support](#browser-support)
+
+## Project Overview
+
+The CoreUI Free Vue Admin Template is a professional admin dashboard built on Vue 3, CoreUI Vue components, and Bootstrap 5. It follows modern Vue patterns with Composition API, script setup syntax, and a component-based architecture.
+
+**Key Features**:
+- Single Page Application (SPA) with client-side routing
+- Responsive design with Bootstrap 5 grid system
+- Dark/Light theme support with automatic detection
+- Lazy loading and code splitting for optimal performance
+- Pinia-based state management
+- Modular and extensible component architecture
+
+## Technology Stack
+
+### Frontend Core
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Vue | 3.5.31 | Progressive framework for building user interfaces |
+| Vue Router | 5.0.4 | Official router for Vue.js |
+| Pinia | 3.0.4 | Official state management library for Vue |
+
+### UI Framework
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| @coreui/coreui | 5.6.1 | CoreUI CSS framework based on Bootstrap 5 |
+| @coreui/vue | 5.8.0 | CoreUI Vue components |
+| @coreui/icons | 3.0.1 | CoreUI icon set |
+| @coreui/icons-vue | 2.2.0 | CoreUI icons as Vue components |
+| @coreui/utils | 2.0.2 | Utility functions for CoreUI |
+| simplebar-vue | 2.4.2 | Custom scrollbar component |
+
+### Data Visualization
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| Chart.js | 4.5.1 | HTML5 charting library |
+| @coreui/chartjs | 4.2.0 | CoreUI Chart.js themes and defaults |
+| @coreui/vue-chartjs | 3.0.0 | Vue wrapper for Chart.js with CoreUI styling |
+
+### Build Tools & Development
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Vite | 8.0.3 | Fast build tool and dev server with HMR |
+| @vitejs/plugin-vue | 6.0.5 | Vite plugin for Vue 3 |
+| Sass | 1.98.0 | CSS preprocessor for styling |
+| PostCSS | 8.5.8 | CSS transformation with autoprefixer |
+| Autoprefixer | 10.4.27 | Automatic vendor prefixing |
+| ESLint | 9.39.4 | JavaScript linting and code quality |
+| eslint-plugin-vue | 10.8.0 | Vue-specific ESLint rules |
+
+### Utilities
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| @popperjs/core | 2.11.8 | Tooltip and popover positioning |
+
+## Architectural Pattern
+
+### Component-Based Architecture
+
+The application follows a **Composition API architecture** with script setup syntax:
+
+```
+┌──────────────────────────────────────────┐
+│         Application (App.vue)            │
+│  - Router View                           │
+│  - Theme Management                      │
+│  - Route Configuration                   │
+└──────────────────────────────────────────┘
+                    ↓
+    ┌───────────────┴────────────────┐
+    │                                │
+┌───▼────┐                  ┌────────▼───────┐
+│ Public │                  │   Protected    │
+│ Routes │                  │     Routes     │
+│        │                  │(DefaultLayout) │
+│ Login  │                  └───────┬────────┘
+│Register│                          │
+│ 404    │              ┌───────────┼────────────┐
+│ 500    │              │           │            │
+└────────┘         ┌────▼────┐ ┌────▼─────┐ ┌────▼─────┐
+                   │AppHeader│ │AppSidebar│ │AppContent│
+                   └─────────┘ └──────────┘ └────┬─────┘
+                                                 │
+                                         ┌───────▼─────────┐
+                                         │ View Components │
+                                         │ (Dashboard,     │
+                                         │  Forms, etc.)   │
+                                         └─────────────────┘
+```
+
+### Single Page Application (SPA) Pattern
+
+The template uses client-side routing with createWebHashHistory:
+1. **Initial Load**: HTML shell loads, Vue initializes
+2. **Route Matching**: Vue Router matches URL to component
+3. **Lazy Loading**: Component bundles load on-demand
+4. **Rendering**: Component renders with layout wrapper
+5. **Navigation**: Client-side transitions without page reload
+
+### State Management Pattern
+
+Pinia manages global application state:
+
+```javascript
+Store (stores/)
+  ├── sidebarVisible (boolean)
+  ├── sidebarUnfoldable (boolean)
+  └── theme (string: light/dark/auto)
+```
+
+Component-level state uses Vue's Composition API (ref, reactive).
+
+## Directory Structure
+
+```
+coreui-free-vue-admin-template/
+│
+├── public/                      # Static assets (served as-is)
+│   ├── favicon.ico
+│   └── robots.txt
+│
+├── src/                         # Source code
+│   │
+│   ├── assets/                  # Application assets
+│   │   ├── brand/              # Logo components (logo.js, sygnet.js)
+│   │   └── images/             # Image files (avatars, etc.)
+│   │
+│   ├── components/              # Reusable UI components
+│   │   ├── AppBreadcrumb.vue   # Breadcrumb navigation
+│   │   ├── AppContent.vue      # Main content area wrapper
+│   │   ├── AppFooter.vue       # Footer component
+│   │   ├── AppHeader.vue       # Header component
+│   │   ├── AppHeaderDropdown.vue # User dropdown menu
+│   │   ├── AppSidebar.vue      # Sidebar navigation
+│   │   ├── DocsComponents.vue  # Documentation component showcase
+│   │   └── DocsExample.vue     # Code example wrapper
+│   │
+│   ├── layouts/                 # Layout wrapper components
+│   │   └── DefaultLayout.vue   # Main application layout
+│   │
+│   ├── views/                   # Page/view components
+│   │   ├── dashboard/          # Dashboard page
+│   │   │   ├── Dashboard.vue
+│   │   │   └── MainChart.vue
+│   │   ├── base/               # Base UI component examples
+│   │   │   ├── Accordion.vue
+│   │   │   ├── Breadcrumbs.vue
+│   │   │   ├── Cards.vue
+│   │   │   ├── Carousels.vue
+│   │   │   ├── Chips.vue
+│   │   │   ├── Collapses.vue
+│   │   │   ├── ListGroups.vue
+│   │   │   ├── Navs.vue
+│   │   │   ├── Paginations.vue
+│   │   │   ├── Placeholders.vue
+│   │   │   ├── Popovers.vue
+│   │   │   ├── Progress.vue
+│   │   │   ├── Spinners.vue
+│   │   │   ├── Tables.vue
+│   │   │   ├── Tabs.vue
+│   │   │   └── Tooltips.vue
+│   │   ├── buttons/            # Button examples
+│   │   ├── charts/             # Chart examples
+│   │   ├── forms/              # Form examples
+│   │   │   └── ChipInput.vue
+│   │   ├── icons/              # Icon examples
+│   │   ├── notifications/      # Notification examples
+│   │   ├── widgets/            # Widget examples
+│   │   ├── theme/              # Theme examples
+│   │   └── pages/              # Special pages
+│   │       ├── Login.vue       # Login page
+│   │       ├── Register.vue    # Registration page
+│   │       ├── Page404.vue     # 404 error page
+│   │       └── Page500.vue     # 500 error page
+│   │
+│   ├── router/                  # Router configuration
+│   │   └── index.js            # Route definitions
+│   │
+│   ├── stores/                  # Pinia stores (if created)
+│   │
+│   ├── scss/                    # Global stylesheets
+│   │   ├── style.scss          # Main stylesheet (imports CoreUI)
+│   │   └── _custom.scss        # Custom style overrides
+│   │
+│   ├── App.vue                  # Root application component
+│   ├── main.js                  # Application entry point
+│   └── _nav.js                  # Sidebar navigation configuration
+│
+├── node_modules/                # Dependencies
+├── index.html                   # HTML entry point
+├── vite.config.mjs              # Vite build configuration
+├── eslint.config.mjs            # ESLint configuration
+├── package.json                 # Project metadata and dependencies
+├── .browserslistrc              # Browser compatibility targets
+├── .editorconfig                # Editor configuration
+└── README.md                    # Project documentation
+```
+
+## Core Components
+
+### Application Component (App.vue)
+
+The root component that:
+- Sets up router-view for component rendering
+- Manages theme initialization
+- Provides the application shell
+
+**Key Features**:
+- Theme detection and persistence
+- Suspense boundaries for lazy-loaded routes
+- Global error handling boundaries
+
+### Layout System
+
+#### DefaultLayout (layouts/DefaultLayout.vue)
+
+The main application layout wrapper that composes:
+- **AppSidebar**: Collapsible navigation sidebar
+- **AppHeader**: Top navigation bar with breadcrumbs and user menu
+- **AppContent**: Main content area with routing
+- **AppFooter**: Footer with version and links
+
+**Responsibility**: Provides consistent layout structure for authenticated views.
+
+#### Navigation Components
+
+**AppSidebar** (`components/AppSidebar.vue`):
+- Renders collapsible sidebar
+- Uses Pinia for show/hide state
+- Integrates with _nav.js for menu structure
+- Includes branding section
+
+**AppHeader** (`components/AppHeader.vue`):
+- Fixed top navigation bar
+- Sidebar toggle button
+- Breadcrumb navigation
+- User dropdown menu
+- Theme switcher
+
+### View Components
+
+View components are page-level components that:
+- Render specific application features (Dashboard, Forms, Charts)
+- Use CoreUI Vue components for UI
+- Connect to Pinia when needed for global state
+- Implement business logic and data fetching
+
+**Example Structure**:
+```vue
+<template>
+  <CCard>
+    <CCardBody>
+      {{ data }}
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const data = ref([])
+
+onMounted(() => {
+  // Fetch dashboard data
+})
+</script>
+```
+
+## Routing System
+
+### Vue Router v5
+
+The application uses Vue Router for declarative routing:
+
+**Configuration** (`router/index.js`):
+```javascript
+import { createRouter, createWebHashHistory } from 'vue-router'
+
+const routes = [
+  {
+    path: '/',
+    name: 'Home',
+    component: DefaultLayout,
+    redirect: '/dashboard',
+    children: [
+      {
+        path: '/dashboard',
+        name: 'Dashboard',
+        component: () => import('@/views/dashboard/Dashboard.vue'),
+      },
+    ],
+  },
+  {
+    path: '/pages',
+    redirect: '/pages/404',
+    name: 'Pages',
+    component: {
+      render() {
+        return h(resolveComponent('router-view'))
+      },
+    },
+    children: [
+      {
+        path: '404',
+        name: 'Page404',
+        component: () => import('@/views/pages/Page404'),
+      },
+    ],
+  },
+]
+
+const router = createRouter({
+  history: createWebHashHistory(import.meta.env.BASE_URL),
+  routes,
+  scrollBehavior() {
+    return { top: 0 }
+  },
+})
+
+export default router
+```
+
+### Lazy Loading & Code Splitting
+
+All routes use dynamic imports for lazy loading:
+
+```javascript
+component: () => import('./views/dashboard/Dashboard.vue')
+```
+
+**Benefits**:
+- Smaller initial bundle size
+- Faster first page load
+- Components load only when navigated to
+- Automatic code splitting by Vite
+
+### Navigation Configuration
+
+Navigation structure defined in `_nav.js`:
+
+```javascript
+export default [
+  {
+    component: 'CNavItem',
+    name: 'Dashboard',
+    to: '/dashboard',
+    icon: 'cil-speedometer',
+    badge: {
+      color: 'info',
+      text: 'NEW',
+    },
+  },
+  {
+    component: 'CNavGroup',
+    name: 'Base',
+    icon: 'cil-puzzle',
+    items: [
+      {
+        component: 'CNavItem',
+        name: 'Accordion',
+        to: '/base/accordion',
+      },
+    ],
+  },
+]
+```
+
+## State Management
+
+### Pinia Store Architecture
+
+Pinia uses the Composition API pattern:
+
+**Store Example** (`stores/main.js`):
+
+```javascript
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+export const useStore = defineStore('main', () => {
+  const sidebarVisible = ref(true)
+  const sidebarUnfoldable = ref(false)
+  const theme = ref('light')
+
+  function toggleSidebar() {
+    sidebarVisible.value = !sidebarVisible.value
+  }
+
+  function setSidebarUnfoldable(value) {
+    sidebarUnfoldable.value = value
+  }
+
+  function setTheme(value) {
+    theme.value = value
+  }
+
+  return {
+    sidebarVisible,
+    sidebarUnfoldable,
+    theme,
+    toggleSidebar,
+    setSidebarUnfoldable,
+    setTheme,
+  }
+})
+```
+
+### State Usage in Components
+
+**Reading State**:
+```vue
+<script setup>
+import { useStore } from '@/stores/main'
+
+const store = useStore()
+// Access: store.sidebarVisible
+</script>
+```
+
+**Updating State**:
+```vue
+<script setup>
+import { useStore } from '@/stores/main'
+
+const store = useStore()
+
+const toggleSidebar = () => {
+  store.toggleSidebar()
+}
+</script>
+```
+
+## Styling Architecture
+
+### Sass/SCSS Structure
+
+**Main Stylesheet** (`src/scss/style.scss`):
+```scss
+@use "@coreui/coreui/scss/coreui" as * with (
+  $enable-deprecation-messages: false
+);
+
+// Custom variables and overrides
+@import 'custom';
+```
+
+**Custom Overrides** (`src/scss/_custom.scss`):
+```scss
+// Override CoreUI/Bootstrap variables
+$primary: #321fdb;
+$secondary: #ced2d8;
+
+// Custom styles
+.my-custom-class {
+  // styles
+}
+```
+
+### CSS Custom Properties (CSS Variables)
+
+CoreUI uses CSS custom properties for theming:
+
+```css
+:root {
+  --cui-primary: #321fdb;
+  --cui-secondary: #ced2d8;
+  --cui-body-bg: #ebedef;
+  --cui-body-color: #4f5d73;
+}
+
+[data-coreui-theme="dark"] {
+  --cui-body-bg: #2b3035;
+  --cui-body-color: #b4bac0;
+}
+```
+
+**Usage in Components**:
+```vue
+<template>
+  <div :style="{ backgroundColor: 'var(--cui-primary)' }">Content</div>
+</template>
+```
+
+### Component Styling
+
+**Scoped Styles**:
+```vue
+<style scoped>
+.my-component {
+  padding: 1rem;
+  background-color: var(--cui-light);
+}
+</style>
+```
+
+**Class Bindings**:
+```vue
+<template>
+  <button :class="['btn', { 'btn-primary': isPrimary, 'active': isActive }]">
+    Click
+  </button>
+</template>
+```
+
+**Bootstrap Utilities**:
+```vue
+<template>
+  <CCard class="mb-4 shadow-sm">
+    <CCardBody class="p-4 d-flex justify-content-between">
+    </CCardBody>
+  </CCard>
+</template>
+```
+
+## Build System
+
+### Vite Configuration
+
+**File**: `vite.config.mjs`
+
+```javascript
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import autoprefixer from 'autoprefixer'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+    extensions: ['.js', '.json', '.jsx', '.mjs', '.ts', '.tsx', '.vue'],
+  },
+  server: {
+    port: 3000,
+  },
+  css: {
+    postcss: {
+      plugins: [autoprefixer()],
+    },
+  },
+})
+```
+
+### Build Process
+
+**Development Build**:
+1. Vite starts dev server on port 3000
+2. esbuild compiles Vue SFC components
+3. PostCSS processes Sass/SCSS with autoprefixer
+4. Hot Module Replacement (HMR) for instant updates
+
+**Production Build**:
+1. `vite build` command
+2. Code minification and tree-shaking
+3. Asset optimization (images, fonts)
+4. CSS extraction and minification
+5. Source maps generation
+6. Output to `dist/` directory
+
+**Build Output**:
+```
+dist/
+├── assets/
+│   ├── index-[hash].js      # Main bundle
+│   ├── [component]-[hash].js # Lazy-loaded chunks
+│   └── index-[hash].css     # Extracted CSS
+├── index.html               # HTML entry
+└── favicon.ico              # Static assets
+```
+
+### Code Splitting Strategy
+
+**Automatic Splitting**:
+- Each lazy-loaded route becomes a separate chunk
+- Vendor libraries (Vue, CoreUI) in separate vendor chunk
+- Dynamic imports create split points
+
+**Manual Splitting** (if needed):
+```javascript
+const HeavyComponent = () => import(/* webpackChunkName: "heavy" */ './HeavyComponent.vue')
+```
+
+## Performance Optimizations
+
+### Implemented Optimizations
+
+1. **Lazy Loading**: All routes lazy-loaded with dynamic imports
+2. **Code Splitting**: Separate bundles per route
+3. **Tree Shaking**: Unused code eliminated by Vite
+4. **Asset Optimization**: Images and fonts optimized
+5. **CSS Extraction**: Separate CSS bundle for caching
+6. **Hash-based Caching**: File names include content hash
+
+### Component Optimization
+
+**v-memo** for expensive renders:
+```vue
+<template>
+  <div v-memo="[valueA, valueB]">
+    <!-- Heavy rendering -->
+  </div>
+</template>
+```
+
+**computed** for derived values:
+```vue
+<script setup>
+import { computed } from 'vue'
+
+const sortedData = computed(() => {
+  return data.value.sort((a, b) => a.value - b.value)
+})
+</script>
+```
+
+### Bundle Size Management
+
+**Strategies**:
+- Use named imports: `import { CButton } from '@coreui/vue'`
+- Avoid importing entire libraries
+- Check bundle size with `npm run build`
+- Use Vite's rollup visualizer for analysis
+
+## Browser Support
+
+### Target Browsers
+
+Defined in `.browserslistrc`:
+```
+> 0.5%
+last 2 versions
+Firefox ESR
+not dead
+not IE 11
+```
+
+### Polyfills
+
+Modern browsers support Vue 3 natively. No additional polyfills needed for ES6+ features.
+
+### Progressive Enhancement
+
+- Modern features with fallbacks
+- CSS Grid with flexbox fallback
+- Modern color modes with theme classes
+
+## Security Considerations
+
+### Best Practices
+
+1. **Content Security Policy**: Configure CSP headers
+2. **XSS Prevention**: Vue escapes content by default
+3. **Dependency Auditing**: Run `npm audit` regularly
+4. **Environment Variables**: Use `.env` files (not committed)
+5. **HTTPS**: Serve over HTTPS in production
+
+### Vue Security
+
+- Avoid `v-html` unless necessary and sanitize content
+- Validate user input before rendering
+- Use prop validation for type safety
+- Keep dependencies updated
+
+## Deployment
+
+### Static Hosting
+
+The application builds to static files suitable for:
+- Netlify
+- Vercel
+- GitHub Pages
+- AWS S3 + CloudFront
+- Any static file server
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+Output in `dist/` directory ready for deployment.
+
+### HashRouter for Static Hosts
+
+Uses createWebHashHistory for GitHub Pages compatibility:
+- URLs: `https://example.com/#/dashboard`
+- No server-side routing configuration needed
+- Works with any static host
+
+---
+
+This architecture provides a solid foundation for building modern, performant admin dashboards with Vue 3 and CoreUI. The modular structure allows for easy extension and customization while maintaining code quality and best practices.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 00000000..2d40e7f4
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,1113 @@
+# CoreUI Free Vue Admin Template - Development Guide
+
+A comprehensive guide for developers working with the CoreUI Free Vue Admin Template. This guide covers setup, development workflows, common patterns, and best practices.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Development Workflow](#development-workflow)
+- [Creating Components](#creating-components)
+- [Adding New Pages](#adding-new-pages)
+- [Working with Routes](#working-with-routes)
+- [State Management](#state-management)
+- [Styling Components](#styling-components)
+- [Working with Forms](#working-with-forms)
+- [Data Visualization](#data-visualization)
+- [Code Quality](#code-quality)
+- [Testing](#testing)
+- [Build and Deployment](#build-and-deployment)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+
+## Prerequisites
+
+### Required Software
+
+- **Node.js**: Version 16 or higher (18+ recommended)
+- **npm**: Version 7+ or **yarn**: Version 1.22+
+- **Git**: For version control
+
+### Recommended Tools
+
+- **Visual Studio Code** with extensions:
+  - Volar (Vue Language Features)
+  - ESLint
+  - Prettier
+  - Auto Import
+  - GitLens
+- **Vue DevTools** browser extension
+
+### Knowledge Requirements
+
+- JavaScript ES6+ features (arrow functions, destructuring, modules)
+- Vue 3 fundamentals (Composition API, reactive, ref, computed)
+- HTML5 and CSS3
+- Sass/SCSS basics
+- Git version control
+
+## Getting Started
+
+### Installation
+
+1. **Clone the repository** (or download the source):
+```bash
+git clone https://github.com/coreui/coreui-free-vue-admin-template.git
+cd coreui-free-vue-admin-template
+```
+
+2. **Install dependencies**:
+```bash
+npm install
+# or
+yarn install
+```
+
+3. **Start the development server**:
+```bash
+npm run dev
+# or
+yarn dev
+```
+
+4. **Open your browser** to [http://localhost:3000](http://localhost:3000)
+
+The development server includes:
+- Hot Module Replacement (HMR) for instant updates
+- Automatic browser refresh on file changes
+- Error overlay for compile-time and runtime errors
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server on port 3000 |
+| `npm run build` | Build optimized production bundle |
+| `npm run preview` | Preview production build locally |
+| `npm run lint` | Run ESLint to check code quality |
+
+## Project Structure
+
+### Source Code Organization
+
+**IMPORTANT**: Always edit source files in `src/`, never modify compiled files in `dist/`.
+
+```
+src/
+├── assets/          # Static assets (images, logos)
+├── components/      # Reusable UI components
+├── layouts/         # Layout wrapper components
+├── views/           # Page/route components
+├── router/          # Router configuration
+├── stores/          # Pinia stores (optional)
+├── scss/            # Global styles and themes
+├── App.vue          # Root component
+├── main.js          # Application entry point
+└── _nav.js          # Navigation menu configuration
+```
+
+### Key Files
+
+- **`App.vue`**: Main application component with router-view
+- **`main.js`**: Vue app creation, plugins, and mounting
+- **`router/index.js`**: Route definitions and configuration
+- **`_nav.js`**: Navigation menu structure for sidebar
+
+## Development Workflow
+
+### Daily Development Process
+
+1. **Start development server**: `npm run dev`
+2. **Make changes** to source files in `src/`
+3. **View changes** instantly in browser (HMR)
+4. **Check console** for errors or warnings
+5. **Run linter** before committing: `npm run lint`
+6. **Test in both themes** (light and dark)
+7. **Commit changes** with conventional commit messages
+
+### Hot Module Replacement (HMR)
+
+Vite provides instant feedback:
+- **Vue SFC changes**: Component updates without page reload
+- **CSS/SCSS changes**: Style updates without reload
+- **Configuration changes**: Require server restart
+
+### Development Server Features
+
+**Port**: 3000 (configurable in `vite.config.mjs`)
+
+**Features**:
+- Fast cold start (~500ms)
+- Instant HMR (<50ms)
+- Error overlay with stack traces
+- Network access for mobile testing
+
+**Access from mobile**:
+```bash
+# Find your local IP
+# Windows: ipconfig
+# Mac/Linux: ifconfig
+
+# Access from mobile device:
+http://192.168.1.X:3000
+```
+
+## Creating Components
+
+### Component Structure
+
+**Composition API with script setup**:
+
+```vue
+<template>
+  <CCard>
+    <CCardHeader>{{ name }}</CCardHeader>
+    <CCardBody>
+      <img v-if="avatar" :src="avatar" :alt="name" />
+      <p>{{ email }}</p>
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+/**
+ * UserCard component displays user information in a card format
+ */
+import { defineProps } from 'vue'
+
+const props = defineProps({
+  /** User's full name */
+  name: {
+    type: String,
+    required: true,
+  },
+  /** User's email address */
+  email: {
+    type: String,
+    required: true,
+  },
+  /** Optional avatar URL */
+  avatar: {
+    type: String,
+    default: null,
+  },
+})
+</script>
+
+<style scoped>
+/* Component-specific styles */
+</style>
+```
+
+### Component Best Practices
+
+1. **Keep components focused**: One responsibility per component
+2. **Use prop validation**: Define types and required props
+3. **Add JSDoc comments**: Document component purpose and props
+4. **Extract logic**: Use composables for reusable logic
+5. **Name meaningfully**: Clear, descriptive component names
+
+### Composables (Custom Hooks)
+
+Extract reusable logic into composables:
+
+```javascript
+// composables/useFetch.js
+import { ref, watch } from 'vue'
+
+/**
+ * Custom composable for fetching data from an API
+ * @param {String} url - API endpoint URL
+ * @returns {Object} { data, loading, error, refetch }
+ */
+export function useFetch(url) {
+  const data = ref(null)
+  const loading = ref(true)
+  const error = ref(null)
+
+  const fetchData = async () => {
+    try {
+      loading.value = true
+      const response = await fetch(url)
+      data.value = await response.json()
+      error.value = null
+    } catch (err) {
+      error.value = err.message
+    } finally {
+      loading.value = false
+    }
+  }
+
+  watch(() => url, fetchData, { immediate: true })
+
+  return { data, loading, error, refetch: fetchData }
+}
+```
+
+**Usage**:
+```vue
+<script setup>
+import { useFetch } from '@/composables/useFetch'
+
+const { data, loading, error } = useFetch('/api/users')
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else-if="error">Error: {{ error }}</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+## Adding New Pages
+
+### Step-by-Step Process
+
+**1. Create the page component** in `src/views/[feature]/`:
+
+```vue
+<!-- src/views/products/Products.vue -->
+<template>
+  <CRow>
+    <CCol :xs="12">
+      <CCard class="mb-4">
+        <CCardHeader>
+          <strong>Products</strong>
+        </CCardHeader>
+        <CCardBody>
+          <!-- Your content here -->
+        </CCardBody>
+      </CCard>
+    </CCol>
+  </CRow>
+</template>
+
+<script setup>
+// Component logic
+</script>
+```
+
+**2. Add route to `src/router/index.js`**:
+
+```javascript
+{
+  path: '/products',
+  name: 'Products',
+  component: () => import('@/views/products/Products.vue'),
+}
+```
+
+**3. Add navigation item to `src/_nav.js`** (optional):
+
+```javascript
+{
+  component: 'CNavItem',
+  name: 'Products',
+  to: '/products',
+  icon: 'cil-basket',
+}
+```
+
+**4. Test the page**:
+- Navigate to `http://localhost:3000/#/products`
+- Check that navigation highlights correctly
+- Verify breadcrumb displays properly
+
+### Page Templates
+
+**List Page**:
+```vue
+<template>
+  <CCard>
+    <CCardHeader>Items</CCardHeader>
+    <CCardBody>
+      <CTable>
+        <CTableHead>
+          <CTableRow>
+            <CTableHeaderCell>Name</CTableHeaderCell>
+            <CTableHeaderCell>Status</CTableHeaderCell>
+          </CTableRow>
+        </CTableHead>
+        <CTableBody>
+          <CTableRow v-for="item in items" :key="item.id">
+            <CTableDataCell>{{ item.name }}</CTableDataCell>
+            <CTableDataCell>{{ item.status }}</CTableDataCell>
+          </CTableRow>
+        </CTableBody>
+      </CTable>
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const items = ref([])
+
+onMounted(async () => {
+  // Fetch items
+})
+</script>
+```
+
+**Detail Page**:
+```vue
+<template>
+  <CSpinner v-if="!item" />
+  <CCard v-else>
+    <CCardHeader>{{ item.name }}</CCardHeader>
+    <CCardBody>
+      <p>{{ item.description }}</p>
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const item = ref(null)
+
+onMounted(async () => {
+  // Fetch item by route.params.id
+})
+</script>
+```
+
+## Working with Routes
+
+### Route Configuration
+
+Routes are defined in `src/router/index.js`:
+
+```javascript
+const routes = [
+  {
+    path: '/',
+    redirect: '/dashboard',
+    name: 'Home',
+    component: DefaultLayout,
+    children: [
+      {
+        path: '/dashboard',
+        name: 'Dashboard',
+        component: () => import('@/views/dashboard/Dashboard.vue'),
+      },
+    ],
+  },
+]
+```
+
+### Dynamic Routes
+
+**With URL parameters**:
+
+```javascript
+// Route definition
+{
+  path: '/products/:id',
+  name: 'Product Detail',
+  component: () => import('@/views/products/ProductDetail.vue'),
+}
+
+// Component usage
+<script setup>
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const productId = route.params.id
+</script>
+```
+
+### Programmatic Navigation
+
+**Using useRouter hook**:
+
+```vue
+<script setup>
+import { useRouter } from 'vue-router'
+
+const router = useRouter()
+
+const goToProducts = () => {
+  router.push('/products')
+}
+
+const goBack = () => {
+  router.back()
+}
+</script>
+
+<template>
+  <CButton @click="goToProducts">View Products</CButton>
+  <CButton @click="goBack">Go Back</CButton>
+</template>
+```
+
+### Protected Routes
+
+Add authentication logic in `router/index.js`:
+
+```javascript
+router.beforeEach((to, from, next) => {
+  const isAuthenticated = localStorage.getItem('token')
+
+  if (to.meta.requiresAuth && !isAuthenticated) {
+    next('/pages/login')
+  } else {
+    next()
+  }
+})
+```
+
+## State Management
+
+### Using Pinia
+
+**Creating a store**:
+
+```javascript
+// stores/main.js
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useStore = defineStore('main', () => {
+  // State
+  const sidebarVisible = ref(true)
+  const theme = ref('light')
+
+  // Getters
+  const isDark = computed(() => theme.value === 'dark')
+
+  // Actions
+  function toggleSidebar() {
+    sidebarVisible.value = !sidebarVisible.value
+  }
+
+  function setTheme(newTheme) {
+    theme.value = newTheme
+  }
+
+  return { sidebarVisible, theme, isDark, toggleSidebar, setTheme }
+})
+```
+
+**Using the store**:
+
+```vue
+<script setup>
+import { useStore } from '@/stores/main'
+
+const store = useStore()
+
+// Read state
+console.log(store.sidebarVisible)
+console.log(store.isDark)
+
+// Call actions
+store.toggleSidebar()
+store.setTheme('dark')
+</script>
+```
+
+### Local Component State
+
+**ref for simple state**:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const isOpen = ref(false)
+const formData = ref({ name: '', email: '' })
+</script>
+```
+
+**reactive for complex state**:
+
+```vue
+<script setup>
+import { reactive } from 'vue'
+
+const state = reactive({
+  count: 0,
+  step: 1,
+  history: [],
+})
+</script>
+```
+
+## Styling Components
+
+### Using CoreUI Components
+
+**ALWAYS use CoreUI Vue components** from `@coreui/vue`:
+
+```vue
+<template>
+  <CRow>
+    <CCol :md="6">
+      <CCard>
+        <CCardHeader>Card Title</CCardHeader>
+        <CCardBody>
+          <CButton color="primary">Click Me</CButton>
+        </CCardBody>
+      </CCard>
+    </CCol>
+  </CRow>
+</template>
+```
+
+### Bootstrap Utilities
+
+Use Bootstrap utility classes for quick styling:
+
+```vue
+<template>
+  <CCard class="mb-4 shadow-sm">
+    <CCardBody class="p-4 d-flex justify-content-between align-items-center">
+      <span class="text-muted">Left</span>
+      <span class="fw-bold">Right</span>
+    </CCardBody>
+  </CCard>
+</template>
+```
+
+**Common utilities**:
+- Spacing: `m-3`, `mt-2`, `mb-4`, `p-3`, `px-4`, `py-2`
+- Display: `d-flex`, `d-none`, `d-block`, `d-inline`
+- Flexbox: `justify-content-between`, `align-items-center`
+- Text: `text-center`, `text-muted`, `fw-bold`, `fs-5`
+
+### Custom Styles
+
+**Component-level SCSS** (scoped):
+
+```vue
+<template>
+  <div class="my-component">
+    <h1 class="my-component__title">Title</h1>
+  </div>
+</template>
+
+<style scoped lang="scss">
+.my-component {
+  padding: 1rem;
+  background-color: var(--cui-light);
+
+  &__title {
+    color: var(--cui-primary);
+    font-size: 1.5rem;
+  }
+}
+</style>
+```
+
+### CSS Custom Properties
+
+Use CoreUI CSS variables for theming:
+
+```vue
+<template>
+  <div :style="{
+    backgroundColor: 'var(--cui-primary)',
+    color: 'var(--cui-white)',
+    padding: 'var(--cui-spacer-3)',
+  }">
+    Styled with CSS variables
+  </div>
+</template>
+```
+
+**Common variables**:
+- Colors: `--cui-primary`, `--cui-secondary`, `--cui-success`, `--cui-danger`
+- Background: `--cui-body-bg`, `--cui-light`, `--cui-dark`
+- Text: `--cui-body-color`, `--cui-text-muted`
+- Spacing: `--cui-spacer-1` through `--cui-spacer-5`
+
+### Conditional Styling
+
+Use class or style bindings:
+
+```vue
+<template>
+  <button
+    :class="['btn', { 'btn-primary': isPrimary, 'btn-secondary': !isPrimary, 'active': isActive }]"
+  >
+    Button
+  </button>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const isPrimary = ref(true)
+const isActive = ref(false)
+</script>
+```
+
+## Working with Forms
+
+### Form Component Example
+
+```vue
+<template>
+  <CCard>
+    <CCardHeader>Contact Form</CCardHeader>
+    <CCardBody>
+      <CForm
+        class="row g-3"
+        :noValidate="true"
+        :validated="validated"
+        @submit.prevent="handleSubmit"
+      >
+        <CCol :md="6">
+          <CFormLabel for="name">Name</CFormLabel>
+          <CFormInput
+            type="text"
+            id="name"
+            v-model="formData.name"
+            required
+          />
+        </CCol>
+        <CCol :md="6">
+          <CFormLabel for="email">Email</CFormLabel>
+          <CFormInput
+            type="email"
+            id="email"
+            v-model="formData.email"
+            required
+          />
+        </CCol>
+        <CCol :xs="12">
+          <CFormLabel for="message">Message</CFormLabel>
+          <CFormTextarea
+            id="message"
+            :rows="3"
+            v-model="formData.message"
+            required
+          />
+        </CCol>
+        <CCol :xs="12">
+          <CButton color="primary" type="submit">
+            Submit
+          </CButton>
+        </CCol>
+      </CForm>
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const formData = ref({
+  name: '',
+  email: '',
+  message: '',
+})
+const validated = ref(false)
+
+const handleSubmit = (event) => {
+  const form = event.target
+
+  if (!form.checkValidity()) {
+    validated.value = true
+    return
+  }
+
+  // Submit form data
+  console.log('Form data:', formData.value)
+}
+</script>
+```
+
+### Form Validation
+
+**HTML5 validation**:
+```vue
+<CFormInput
+  type="email"
+  required
+  pattern="[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$"
+/>
+```
+
+**Custom validation**:
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const errors = ref({})
+
+const validate = () => {
+  const newErrors = {}
+
+  if (!formData.value.name) {
+    newErrors.name = 'Name is required'
+  }
+
+  if (!formData.value.email.includes('@')) {
+    newErrors.email = 'Invalid email address'
+  }
+
+  errors.value = newErrors
+  return Object.keys(newErrors).length === 0
+}
+
+const handleSubmit = () => {
+  if (validate()) {
+    // Submit form
+  }
+}
+</script>
+```
+
+## Data Visualization
+
+### Using Chart.js with CoreUI
+
+```vue
+<template>
+  <CCard>
+    <CCardHeader>Sales Overview</CCardHeader>
+    <CCardBody>
+      <CChartLine
+        :data="chartData"
+        :options="chartOptions"
+        style="height: 300px"
+      />
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { CChartLine } from '@coreui/vue-chartjs'
+
+const chartData = {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
+  datasets: [
+    {
+      label: 'Sales 2024',
+      backgroundColor: 'rgba(220, 53, 69, 0.1)',
+      borderColor: 'rgba(220, 53, 69, 1)',
+      data: [40, 20, 12, 39, 10, 40, 39],
+    },
+  ],
+}
+
+const chartOptions = {
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: {
+      display: true,
+    },
+  },
+}
+</script>
+```
+
+### Chart Types
+
+CoreUI provides Vue wrappers for Chart.js:
+
+- `CChartLine` - Line charts
+- `CChartBar` - Bar charts
+- `CChartDoughnut` - Doughnut charts
+- `CChartPie` - Pie charts
+- `CChartPolarArea` - Polar area charts
+- `CChartRadar` - Radar charts
+
+## Code Quality
+
+### ESLint Configuration
+
+The project uses ESLint with Vue and Prettier plugins:
+
+```bash
+# Check for issues
+npm run lint
+
+# Auto-fix issues (when possible)
+npm run lint -- --fix
+```
+
+### Code Style Guidelines
+
+**JavaScript**:
+- No semicolons (enforced by Prettier)
+- Single quotes for strings
+- 2-space indentation
+- Arrow functions preferred
+- Destructuring when possible
+
+**Vue**:
+- Composition API with script setup
+- Props defined with defineProps()
+- Meaningful component names
+- Scoped styles
+
+**File naming**:
+- PascalCase for components: `UserCard.vue`
+- camelCase for utilities: `dateHelper.js`
+- kebab-case for styles: `user-card.scss`
+
+### Pre-commit Checks
+
+**Recommended**: Set up pre-commit hooks with Husky:
+
+```bash
+npm install --save-dev husky lint-staged
+
+# Add to package.json
+{
+  "lint-staged": {
+    "src/**/*.{js,vue}": ["eslint --fix", "prettier --write"]
+  }
+}
+```
+
+## Testing
+
+### Manual Testing Checklist
+
+Before committing changes:
+
+- [ ] Test in both light and dark themes
+- [ ] Test responsive design (mobile, tablet, desktop)
+- [ ] Check browser console for errors
+- [ ] Verify all links and navigation work
+- [ ] Test form validation and submission
+- [ ] Check accessibility (keyboard navigation, screen readers)
+
+### Browser Testing
+
+Test in modern browsers:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+### Responsive Testing
+
+Test at common breakpoints:
+- Mobile: 375px, 414px
+- Tablet: 768px, 1024px
+- Desktop: 1366px, 1920px
+
+**Tip**: Use Chrome DevTools device toolbar (Cmd/Ctrl + Shift + M)
+
+## Build and Deployment
+
+### Production Build
+
+Create optimized production build:
+
+```bash
+npm run build
+```
+
+Output in `dist/` directory:
+- Minified JavaScript bundles
+- Extracted and minified CSS
+- Optimized assets
+- Source maps
+
+### Build Analysis
+
+Check bundle size:
+
+```bash
+npm run build
+
+# Output shows:
+# - Total bundle size
+# - Individual chunk sizes
+# - Asset sizes
+```
+
+### Preview Production Build
+
+Test production build locally:
+
+```bash
+npm run preview
+```
+
+Opens preview server at `http://localhost:4173`
+
+### Deployment Platforms
+
+**Static hosting** (builds to static files):
+
+1. **Netlify**:
+   - Connect GitHub repository
+   - Build command: `npm run build`
+   - Publish directory: `dist`
+
+2. **Vercel**:
+   - Import Git repository
+   - Framework preset: Vite
+   - Build command: `npm run build`
+
+3. **GitHub Pages**:
+   - Build locally: `npm run build`
+   - Push `dist/` folder to `gh-pages` branch
+
+4. **AWS S3 + CloudFront**:
+   - Upload `dist/` contents to S3 bucket
+   - Configure CloudFront distribution
+
+### Environment Variables
+
+Create `.env` file (not committed to Git):
+
+```bash
+VITE_API_URL=https://api.example.com
+VITE_APP_NAME=My App
+```
+
+**Usage in code**:
+```javascript
+const apiUrl = import.meta.env.VITE_API_URL
+```
+
+**IMPORTANT**: Only variables prefixed with `VITE_` are exposed to the app.
+
+## Troubleshooting
+
+### Common Issues
+
+**Problem**: Port 3000 already in use
+
+**Solution**:
+```bash
+# Kill process on port 3000
+# Mac/Linux:
+lsof -ti:3000 | xargs kill
+
+# Windows:
+netstat -ano | findstr :3000
+taskkill /PID <PID> /F
+
+# Or change port in vite.config.mjs
+```
+
+---
+
+**Problem**: Module not found errors
+
+**Solution**:
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+---
+
+**Problem**: Styles not updating
+
+**Solution**:
+- Clear browser cache
+- Hard refresh (Cmd/Ctrl + Shift + R)
+- Restart dev server
+
+---
+
+**Problem**: HMR not working
+
+**Solution**:
+- Check file is saved
+- Restart dev server
+- Check for syntax errors in console
+
+---
+
+**Problem**: Build fails with memory error
+
+**Solution**:
+```bash
+# Increase Node memory limit
+NODE_OPTIONS="--max-old-space-size=4096" npm run build
+```
+
+### Debugging Tips
+
+**Vue DevTools**:
+- Inspect component hierarchy
+- View props and state
+- Profile component renders
+- Inspect Pinia stores
+
+**Console logging**:
+```javascript
+console.log('Variable:', variable)
+console.table(arrayOfObjects)
+console.error('Error:', error)
+```
+
+## Best Practices
+
+### Performance
+
+1. **Lazy load routes**: Use dynamic imports for code splitting
+2. **Use computed**: For derived values instead of methods
+3. **Optimize re-renders**: Use v-memo for expensive renders
+4. **Virtualize long lists**: Use libraries like vue-virtual-scroller
+5. **Optimize images**: Use WebP format, lazy loading
+
+### Accessibility
+
+1. **Semantic HTML**: Use proper heading hierarchy (h1-h6)
+2. **ARIA labels**: Add aria-label for icon buttons
+3. **Keyboard navigation**: Ensure all interactive elements are keyboard-accessible
+4. **Color contrast**: Meet WCAG AA standards (4.5:1 for text)
+5. **Form labels**: Associate all form inputs with labels
+
+### Security
+
+1. **Validate input**: Sanitize user input before rendering
+2. **Use HTTPS**: Always serve over HTTPS in production
+3. **Content Security Policy**: Configure CSP headers
+4. **Dependency audits**: Run `npm audit` regularly
+5. **Environment variables**: Never commit secrets to Git
+
+### Code Organization
+
+1. **Single Responsibility**: One component does one thing well
+2. **DRY Principle**: Don't Repeat Yourself - extract reusable code
+3. **Consistent naming**: Follow naming conventions throughout
+4. **File organization**: Group related files together
+5. **Documentation**: Comment complex logic and add JSDoc
+
+### Git Workflow
+
+**Commit messages** (Conventional Commits):
+```
+feat: add user profile page
+fix: resolve navigation bug on mobile
+docs: update README with deployment instructions
+style: format code with Prettier
+refactor: extract form validation logic
+test: add tests for UserCard component
+chore: update dependencies
+```
+
+**Branch naming**:
+```
+feature/user-profile
+fix/navigation-bug
+refactor/form-validation
+docs/deployment-guide
+```
+
+---
+
+This guide covers the essential workflows and patterns for developing with the CoreUI Free Vue Admin Template. For additional questions, consult the [CoreUI Vue Documentation](https://coreui.io/vue/docs/) or the [Vue 3 Documentation](https://vuejs.org/).
+
+Happy coding! 🚀
diff --git a/README.md b/README.md
index debd71da..e04bb013 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# CoreUI Free Vue Admin Template [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&logo=twitter)](https://twitter.com/intent/tweet?text=CoreUI%20-%20Free%Vue%204%20Admin%20Template%20&url=https://coreui.io&hashtags=bootstrap,admin,template,dashboard,panel,free,angular,react,vue)
+# CoreUI Free Vue Admin Template - Built for AI-Assisted Development [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&logo=twitter)](https://twitter.com/intent/tweet?text=CoreUI%20-%20Free%Vue%204%20Admin%20Template%20&url=https://coreui.io&hashtags=bootstrap,admin,template,dashboard,panel,free,angular,react,vue)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![@coreui coreui](https://img.shields.io/badge/@coreui%20-coreui-lightgrey.svg?style=flat-square)](https://github.com/coreui/coreui)
@@ -29,6 +29,7 @@ CoreUI is meant to be the UX game changer. Pure & transparent code is devoid of
 * [Installation](#installation)
 * [Basic usage](#basic-usage)
 * [What's included](#whats-included)
+* [AI-Friendly Development](#ai-friendly-development)
 * [Documentation](#documentation)
 * [Components](#components)
 * [Versioning](#versioning)
@@ -135,6 +136,43 @@ coreui-free-vue-admin-template
 └── vite.config.mjs
 ```
 
+## AI-Friendly Development
+
+This template is designed to work seamlessly with AI coding assistants like Cursor, GitHub Copilot, and Claude Code. We've included comprehensive documentation and configuration files to help AI understand the project structure and conventions.
+
+### Features for AI Development
+
+- **`.cursorrules`**: Complete AI assistant configuration with project conventions, technology stack, and coding patterns
+- **`ARCHITECTURE.md`**: Detailed technical architecture documentation covering components, routing, state management, and build system
+- **`DEVELOPMENT.md`**: Comprehensive development guide with setup instructions, workflows, and best practices
+- **JSDoc Comments**: Main Vue components include documentation for better AI understanding
+
+### Getting Started with AI Assistants
+
+1. **Open the project** in your AI-powered IDE (VS Code with Cursor, GitHub Copilot, or Claude Code)
+2. **Review `.cursorrules`** to understand the project conventions
+3. **Ask your AI assistant** to help you build features - it will automatically follow the project patterns
+4. **Use natural language** to describe components, pages, or features you want to add
+
+### What AI Assistants Know About This Project
+
+Your AI assistant understands:
+- **Component Library**: Always use CoreUI Vue components (never Tailwind, Vuetify, or other libraries)
+- **Code Style**: Vue 3 Composition API with `<script setup>` syntax, Prettier formatting, ESLint rules
+- **Architecture**: Single Page Application with Vue Router, Pinia for state management, Vite for building
+- **File Organization**: Where to create components, views, routes, and styles
+- **Common Patterns**: Lazy loading, composables, navigation configuration, theming
+
+### Example AI Prompts
+
+Try asking your AI assistant:
+- "Create a new products page with a table showing product name, price, and status"
+- "Add a user profile form with validation"
+- "Create a chart showing monthly sales data"
+- "Add a new navigation item for the settings page"
+
+For more information, see the [DEVELOPMENT.md](DEVELOPMENT.md) guide.
+
 ## Documentation
 
 The documentation for the CoreUI Admin Template is hosted at our website [CoreUI for Vue](https://coreui.io/vue/docs/templates/installation.html)
diff --git a/src/App.vue b/src/App.vue
index a095fda4..d39529ed 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,9 +1,23 @@
 <script setup>
+/**
+ * App.vue - Main Application Component
+ *
+ * This is the root component of the CoreUI Free Vue Admin Template.
+ * It handles theme initialization and provides the router-view for all routes.
+ *
+ * Key responsibilities:
+ * - Theme detection from URL parameters
+ * - Theme persistence with localStorage
+ * - Router view rendering for SPA navigation
+ *
+ * @component
+ */
 import { onBeforeMount } from 'vue'
 import { useColorModes } from '@coreui/vue'
 
 import { useThemeStore } from '@/stores/theme.js'
 
+// Initialize CoreUI color modes with local storage key
 const { isColorModeSet, setColorMode } = useColorModes(
   'coreui-free-vue-admin-template-theme',
 )
diff --git a/src/_nav.js b/src/_nav.js
index 4abb3200..a8a74d74 100644
--- a/src/_nav.js
+++ b/src/_nav.js
@@ -1,3 +1,26 @@
+/**
+ * _nav.js - Sidebar Navigation Configuration
+ *
+ * This file defines the structure and content of the sidebar navigation menu.
+ * The navigation is rendered by AppSidebar component using CoreUI nav components.
+ *
+ * Navigation item types:
+ * - CNavItem: Single navigation link
+ * - CNavGroup: Expandable group of navigation items
+ * - CNavTitle: Section title/divider
+ *
+ * Each item can have:
+ * - component: CoreUI component type ('CNavItem', 'CNavGroup', 'CNavTitle')
+ * - name: Display text
+ * - to: Vue Router path (for CNavItem)
+ * - icon: CoreUI icon name (from @coreui/icons)
+ * - badge: Optional badge with color and text
+ * - items: Array of child items (for CNavGroup)
+ * - href: External link URL
+ * - external: Boolean for external links
+ *
+ * @type {Array<Object>}
+ */
 export default [
   {
     component: 'CNavItem',
diff --git a/src/main.js b/src/main.js
index 64a416a6..b4e39eac 100644
--- a/src/main.js
+++ b/src/main.js
@@ -1,24 +1,52 @@
+/**
+ * main.js - Application Entry Point
+ *
+ * This file initializes the Vue 3 application and configures:
+ * - Pinia for state management
+ * - Vue Router for client-side routing
+ * - CoreUI Vue component library
+ * - Global icon system
+ * - Documentation helper components
+ *
+ * The application uses:
+ * - Vue 3 Composition API
+ * - Vite for building and development
+ * - CoreUI Vue components
+ * - Hash-based routing for static hosting compatibility
+ */
+
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
 
 import App from './App.vue'
 import router from './router'
 
+// CoreUI Vue components and icons
 import CoreuiVue from '@coreui/vue'
 import CIcon from '@coreui/icons-vue'
 import { iconsSet as icons } from '@/assets/icons'
+
+// Documentation components (remove in production if not needed)
 import DocsComponents from '@/components/DocsComponents'
 import DocsExample from '@/components/DocsExample'
 import DocsIcons from '@/components/DocsIcons'
 
+// Create Vue application instance
 const app = createApp(App)
-app.use(createPinia())
-app.use(router)
-app.use(CoreuiVue)
+
+// Install plugins
+app.use(createPinia()) // State management
+app.use(router) // Router for SPA navigation
+app.use(CoreuiVue) // CoreUI component library
+
+// Provide icons globally
 app.provide('icons', icons)
+
+// Register global components
 app.component('CIcon', CIcon)
 app.component('DocsComponents', DocsComponents)
 app.component('DocsExample', DocsExample)
 app.component('DocsIcons', DocsIcons)
 
+// Mount application to DOM
 app.mount('#app')
diff --git a/src/router/index.js b/src/router/index.js
index 378bc250..5107373b 100644
--- a/src/router/index.js
+++ b/src/router/index.js
@@ -1,8 +1,36 @@
+/**
+ * router/index.js - Vue Router Configuration
+ *
+ * This file configures the application routing using Vue Router 5.
+ * It defines all routes and navigation structure for the SPA.
+ *
+ * Routing Features:
+ * - Hash-based routing (createWebHashHistory) for static hosting compatibility
+ * - Lazy loading for all route components (code splitting)
+ * - Nested routes for layout-based navigation
+ * - Automatic scroll to top on navigation
+ *
+ * Route Structure:
+ * - Protected routes: Wrapped in DefaultLayout with sidebar and header
+ * - Public routes: Login, Register, 404, 500 pages without layout
+ *
+ * Adding New Routes:
+ * 1. Import component (use dynamic import for code splitting)
+ * 2. Add route object to appropriate section
+ * 3. Update _nav.js for sidebar navigation (if needed)
+ *
+ * @see https://router.vuejs.org/
+ */
+
 import { h, resolveComponent } from 'vue'
 import { createRouter, createWebHashHistory } from 'vue-router'
 
 import DefaultLayout from '@/layouts/DefaultLayout'
 
+/**
+ * Application routes configuration
+ * @type {Array<Object>}
+ */
 const routes = [
   {
     path: '/',