appiq-solution 1.3.3 → 1.4.3

package/#Tools/APPIQ-METHOD/bmad-core/data/shadcn-ui-integration.md

@@ -0,0 +1,388 @@
+# shadcn/ui Integration Guide
+
+## 📋 Overview
+
+This guide provides comprehensive integration instructions for shadcn/ui components with MCP @21st-dev/magic tool integration for enhanced React development workflows.
+
+## 🎯 shadcn/ui Framework Support
+
+### What is shadcn/ui?
+
+shadcn/ui is a collection of reusable components built using Radix UI and Tailwind CSS. It's designed to be:
+- **Copy & Paste**: Components you can copy and paste into your apps
+- **Customizable**: Fully customizable and extensible
+- **Accessible**: Built on Radix UI primitives for accessibility
+- **Modern**: Uses the latest React patterns and TypeScript
+
+### Key Features
+
+- **Headless Components**: Built on Radix UI primitives
+- **Tailwind CSS**: Styled with Tailwind CSS utility classes
+- **TypeScript**: Full TypeScript support with proper type definitions
+- **Dark Mode**: Built-in dark mode support
+- **Theming**: Comprehensive theming system
+- **Responsive**: Mobile-first responsive design
+
+## 🛠️ MCP @21st-dev/magic Integration
+
+### MCP Tool Capabilities
+
+The @21st-dev/magic MCP tool provides:
+- **Component Generation**: Generate shadcn/ui components with proper setup
+- **Theme Management**: Manage and customize themes programmatically
+- **Component Customization**: Modify existing components with variations
+- **Template Creation**: Create component templates for reuse
+- **Code Analysis**: Analyze component usage and optimization opportunities
+
+### Setup Instructions
+
+1. **Install MCP Tool**
+```bash
+npm install -g @21st-dev/magic
+```
+
+2. **Configure MCP in Project**
+```json
+// .mcp-config.json
+{
+  "tools": {
+    "@21st-dev/magic": {
+      "enabled": true,
+      "config": {
+        "framework": "react",
+        "ui-library": "shadcn/ui",
+        "styling": "tailwind",
+        "typescript": true
+      }
+    }
+  }
+}
+```
+
+3. **Initialize shadcn/ui**
+```bash
+npx shadcn-ui@latest init
+```
+
+## 🎨 Component Architecture
+
+### Component Structure
+
+```
+src/
+├── components/
+│   ├── ui/                 # shadcn/ui components
+│   │   ├── button.tsx
+│   │   ├── card.tsx
+│   │   ├── dialog.tsx
+│   │   └── ...
+│   ├── custom/            # Custom components
+│   │   ├── data-table.tsx
+│   │   ├── form-builder.tsx
+│   │   └── ...
+│   └── layout/            # Layout components
+│       ├── header.tsx
+│       ├── sidebar.tsx
+│       └── footer.tsx
+├── lib/
+│   ├── utils.ts           # Utility functions (cn, etc.)
+│   └── validations.ts     # Form validation schemas
+└── styles/
+    └── globals.css        # Global styles and CSS variables
+```
+
+### Component Categories
+
+#### Core UI Components
+- **Button**: Various button styles and sizes
+- **Input**: Form input components with validation
+- **Card**: Content containers with headers and footers
+- **Dialog**: Modal dialogs and sheets
+- **Dropdown**: Dropdown menus and select components
+- **Navigation**: Navigation menus and breadcrumbs
+
+#### Data Display
+- **Table**: Data tables with sorting and filtering
+- **Badge**: Status indicators and labels
+- **Avatar**: User profile images and initials
+- **Skeleton**: Loading state placeholders
+- **Progress**: Progress bars and indicators
+
+#### Form Components
+- **Form**: Form wrapper with validation
+- **Label**: Form field labels
+- **Checkbox**: Checkbox inputs
+- **Radio**: Radio button groups
+- **Switch**: Toggle switches
+- **Textarea**: Multi-line text inputs
+
+#### Layout Components
+- **Sheet**: Slide-out panels and drawers
+- **Tabs**: Tabbed content organization
+- **Accordion**: Collapsible content sections
+- **Separator**: Visual content dividers
+- **Scroll Area**: Custom scrollable areas
+
+## 🎯 Development Patterns
+
+### Component Creation with MCP
+
+```typescript
+// Using MCP @21st-dev/magic to generate components
+import { magic } from '@21st-dev/magic';
+
+// Generate a new shadcn/ui component
+const component = await magic.generate({
+  type: 'component',
+  name: 'UserProfile',
+  baseComponent: 'card',
+  props: {
+    user: 'User',
+    showActions: 'boolean',
+    onEdit: '() => void'
+  },
+  styling: {
+    theme: 'default',
+    variant: 'outline'
+  }
+});
+```
+
+### Theme Customization
+
+```css
+/* globals.css - CSS Variables for theming */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96%;
+    --secondary-foreground: 222.2 84% 4.9%;
+    --muted: 210 40% 96%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96%;
+    --accent-foreground: 222.2 84% 4.9%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 221.2 83.2% 53.3%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    /* ... dark mode variables */
+  }
+}
+```
+
+### Utility Functions
+
+```typescript
+// lib/utils.ts
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+// Form validation with Zod
+import { z } from "zod";
+
+export const userSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters"),
+  email: z.string().email("Invalid email address"),
+  age: z.number().min(18, "Must be at least 18 years old"),
+});
+
+export type User = z.infer<typeof userSchema>;
+```
+
+## 🚀 Integration with BMAD Workflow
+
+### Agent Integration
+
+#### Frontend Developer Agent Enhancement
+```yaml
+# Enhanced commands for shadcn/ui support
+commands:
+  - create-shadcn-component: Generate shadcn/ui component with MCP magic
+  - customize-theme: Customize theme variables and dark mode
+  - optimize-components: Analyze and optimize component usage
+  - generate-form: Create form components with validation
+  - create-data-table: Generate data table with sorting and filtering
+```
+
+#### MCP Tool Integration
+```typescript
+// Integration with MCP tools in development workflow
+interface MCPShadcnIntegration {
+  generateComponent(spec: ComponentSpec): Promise<ComponentCode>;
+  customizeTheme(theme: ThemeConfig): Promise<CSSVariables>;
+  analyzeUsage(project: ProjectStructure): Promise<UsageReport>;
+  optimizeBundle(components: ComponentList): Promise<OptimizationSuggestions>;
+}
+```
+
+### Workflow Integration
+
+1. **Component Planning**: Use MCP to analyze requirements and suggest components
+2. **Generation**: Generate base components with proper TypeScript types
+3. **Customization**: Apply project-specific styling and behavior
+4. **Integration**: Integrate with existing state management and data flow
+5. **Testing**: Generate tests for components with proper mocking
+6. **Optimization**: Analyze bundle size and optimize imports
+
+## 📋 Best Practices
+
+### Component Development
+- **Composition over Inheritance**: Build complex components from simple ones
+- **Prop Drilling Avoidance**: Use React Context for deep prop passing
+- **TypeScript First**: Always define proper TypeScript interfaces
+- **Accessibility**: Ensure all components meet WCAG guidelines
+- **Performance**: Use React.memo and useMemo for expensive operations
+
+### Styling Guidelines
+- **Utility First**: Use Tailwind utility classes primarily
+- **CSS Variables**: Use CSS custom properties for theming
+- **Responsive Design**: Mobile-first responsive approach
+- **Dark Mode**: Support both light and dark themes
+- **Consistent Spacing**: Use consistent spacing scale
+
+### State Management Integration
+```typescript
+// Integration with state management
+interface ComponentWithState {
+  // Zustand integration
+  useStore: <T>(selector: (state: State) => T) => T;
+  
+  // React Query integration
+  useQuery: <T>(key: string, fetcher: () => Promise<T>) => QueryResult<T>;
+  
+  // Form state management
+  useForm: <T>(schema: ZodSchema<T>) => FormMethods<T>;
+}
+```
+
+## 🔧 Development Commands
+
+### Component Generation
+```bash
+# Generate new component with MCP
+npx @21st-dev/magic generate component UserCard --base=card --props="user:User,onEdit:()=>void"
+
+# Add shadcn/ui component
+npx shadcn-ui@latest add button card dialog
+
+# Customize existing component
+npx @21st-dev/magic customize button --variant=ghost --size=lg
+```
+
+### Theme Management
+```bash
+# Generate theme variations
+npx @21st-dev/magic theme create --name=corporate --primary="#1a365d"
+
+# Export theme variables
+npx @21st-dev/magic theme export --format=css --output=theme.css
+```
+
+### Code Analysis
+```bash
+# Analyze component usage
+npx @21st-dev/magic analyze components --report=usage
+
+# Bundle optimization
+npx @21st-dev/magic optimize --target=bundle-size --threshold=100kb
+```
+
+## 🧪 Testing Strategy
+
+### Component Testing
+```typescript
+// Component test with shadcn/ui
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Button } from '@/components/ui/button';
+
+describe('Button Component', () => {
+  it('renders with correct variant', () => {
+    render(<Button variant="destructive">Delete</Button>);
+    
+    const button = screen.getByRole('button', { name: /delete/i });
+    expect(button).toHaveClass('bg-destructive');
+  });
+
+  it('handles click events', () => {
+    const handleClick = jest.fn();
+    render(<Button onClick={handleClick}>Click me</Button>);
+    
+    fireEvent.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Visual Testing
+```typescript
+// Storybook integration for visual testing
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from '@/components/ui/button';
+
+const meta: Meta<typeof Button> = {
+  title: 'UI/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: {
+    variant: 'default',
+    children: 'Button',
+  },
+};
+```
+
+## 🔒 Security Considerations
+
+### Input Validation
+- **Sanitization**: Sanitize all user inputs before rendering
+- **XSS Prevention**: Use proper escaping for dynamic content
+- **CSRF Protection**: Implement CSRF tokens for forms
+- **Content Security Policy**: Configure CSP headers properly
+
+### Component Security
+- **Prop Validation**: Validate all component props
+- **Safe Rendering**: Avoid dangerouslySetInnerHTML
+- **Access Control**: Implement proper role-based access
+- **Audit Dependencies**: Regular security audits of dependencies
+
+## 📊 Performance Optimization
+
+### Bundle Optimization
+- **Tree Shaking**: Import only used components
+- **Code Splitting**: Split components into separate bundles
+- **Lazy Loading**: Lazy load heavy components
+- **Bundle Analysis**: Regular bundle size analysis
+
+### Runtime Performance
+- **Memoization**: Use React.memo for expensive components
+- **Virtual Scrolling**: For large lists and tables
+- **Image Optimization**: Optimize images and use proper formats
+- **Caching**: Implement proper caching strategies
+
+This integration guide ensures shadcn/ui is properly integrated into the BMAD framework with full MCP tool support for enhanced development workflows.

package/#Tools/APPIQ-METHOD/bmad-core/data/technical-preferences.md

@@ -1,3 +1,149 @@
 # User-Defined Preferred Patterns and Preferences
 
-None Listed
+## Frontend Frameworks
+
+### Web Development
+- **React**: Latest stable version with TypeScript
+- **Next.js**: Full-stack React framework with App Router
+- **Vue 3**: Composition API with TypeScript
+- **Angular**: Latest LTS version with standalone components
+- **Svelte/SvelteKit**: Modern reactive framework
+
+### UI Component Libraries
+- **shadcn/ui**: Modern React components with Tailwind CSS
+- **Material UI**: React components following Material Design
+- **Ant Design**: Enterprise-class UI design language
+- **Chakra UI**: Modular and accessible component library
+- **Headless UI**: Unstyled, accessible UI components
+
+### CSS Frameworks
+- **Tailwind CSS**: Utility-first CSS framework
+- **CSS Modules**: Localized CSS
+- **Styled Components**: CSS-in-JS library
+- **Emotion**: Performant and flexible CSS-in-JS
+
+## Mobile Development
+
+### Flutter
+- **Framework**: Flutter 3.24+ with Dart 3.5+
+- **State Management**: Cubit/BLoC pattern with flutter_bloc
+- **Architecture**: Clean Architecture with dependency injection
+- **Code Generation**: Freezed + json_serializable + injectable
+- **Networking**: Dio HTTP client
+- **Local Storage**: Hive for complex data, SharedPreferences for simple data
+- **Routing**: GoRouter for declarative routing
+- **Localization**: flutter_localizations with ARB files
+- **Testing**: flutter_test + bloc_test + mocktail
+
+## Backend Services
+
+### Firebase
+- **Authentication**: Firebase Auth with multi-provider support
+- **Database**: Firestore for NoSQL, Realtime Database for real-time features
+- **Storage**: Firebase Storage for file uploads
+- **Functions**: Cloud Functions for serverless backend logic
+- **Hosting**: Firebase Hosting for web deployment
+- **Analytics**: Firebase Analytics and Crashlytics
+
+### Supabase
+- **Database**: PostgreSQL with Row Level Security (RLS)
+- **Authentication**: Supabase Auth with social providers
+- **Storage**: Supabase Storage for file management
+- **Real-time**: Real-time subscriptions
+- **Edge Functions**: Deno-based serverless functions
+- **API**: Auto-generated REST and GraphQL APIs
+
+### Traditional Backend
+- **Node.js**: Express.js or Fastify with TypeScript
+- **Python**: FastAPI or Django with type hints
+- **Database**: PostgreSQL for relational, MongoDB for document-based
+- **API**: REST with OpenAPI documentation or GraphQL
+
+## Development Tools
+
+### Build Tools
+- **Vite**: Fast build tool for modern web development
+- **Webpack**: Module bundler for complex configurations
+- **Turbo**: High-performance build system for monorepos
+- **esbuild**: Extremely fast JavaScript bundler
+
+### State Management
+- **Web**: Redux Toolkit, Zustand, or Valtio
+- **Mobile**: Cubit/BLoC for Flutter, Redux for React Native
+
+### Testing
+- **Unit Testing**: Jest, Vitest, or Flutter Test
+- **Integration Testing**: Cypress, Playwright, or Flutter Integration Tests
+- **E2E Testing**: Playwright or Detox for mobile
+
+### Code Quality
+- **Linting**: ESLint for JavaScript/TypeScript, flutter_lints for Flutter
+- **Formatting**: Prettier for web, dart format for Flutter
+- **Type Checking**: TypeScript strict mode, Dart null safety
+
+## Architecture Patterns
+
+### Clean Architecture
+- **Presentation Layer**: UI components and state management
+- **Domain Layer**: Business logic and entities
+- **Data Layer**: Data sources and repository implementations
+- **Infrastructure**: External services and frameworks
+
+### Design Patterns
+- **Repository Pattern**: Abstract data access
+- **Dependency Injection**: Inversion of control
+- **Observer Pattern**: State management and reactive programming
+- **Factory Pattern**: Object creation
+- **Singleton Pattern**: Shared services and utilities
+
+## Security Preferences
+
+### Authentication
+- **Multi-factor Authentication**: Always enabled for production
+- **OAuth 2.0**: Preferred for third-party authentication
+- **JWT Tokens**: With proper expiration and refresh mechanisms
+- **Biometric Authentication**: For mobile applications where applicable
+
+### Data Protection
+- **Encryption at Rest**: All sensitive data encrypted
+- **Encryption in Transit**: HTTPS/TLS for all communication
+- **Input Validation**: Server-side validation for all inputs
+- **SQL Injection Prevention**: Parameterized queries or ORM
+
+### API Security
+- **Rate Limiting**: Prevent abuse and DoS attacks
+- **CORS Configuration**: Proper cross-origin resource sharing
+- **API Keys**: Secure API key management
+- **Certificate Pinning**: For mobile applications
+
+## Performance Preferences
+
+### Web Performance
+- **Core Web Vitals**: Optimize for LCP, FID, and CLS
+- **Code Splitting**: Lazy loading for better performance
+- **Image Optimization**: WebP format with fallbacks
+- **Caching Strategy**: Service workers and CDN caching
+
+### Mobile Performance
+- **60 FPS**: Maintain smooth animations and scrolling
+- **Memory Management**: Efficient memory usage and garbage collection
+- **Battery Optimization**: Minimize battery drain
+- **Offline Support**: Graceful offline functionality
+
+## Localization Preferences
+
+### Multi-language Support
+- **Internationalization**: Built-in from project start
+- **Translation Keys**: Descriptive and hierarchical
+- **RTL Support**: Right-to-left language support
+- **Date/Time Formatting**: Locale-specific formatting
+- **Number Formatting**: Currency and number localization
+
+## MCP Tool Integrations
+
+### Available MCP Tools
+- **@21st-dev/magic**: For shadcn/ui component generation and management
+- **supabase-mcp**: For Supabase backend integration and management
+- **firebase-mcp**: For Firebase services integration
+- **sequential-thinking**: For complex problem analysis and decision making
+- **dart-mcp**: For Dart code analysis and Flutter development assistance

package/#Tools/APPIQ-METHOD/bmad-core/enhanced-ide-development-workflow.md

@@ -0,0 +1,43 @@
+# Enhanced Development Workflow
+
+This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
+
+## Create new Branch
+
+1. **Start new branch**
+
+## Story Creation (Scrum Master)
+
+1. **Start new chat/conversation**
+2. **Load SM agent**
+3. **Execute**: `*draft` (runs create-next-story task)
+4. **Review generated story** in `docs/stories/`
+5. **Update status**: Change from "Draft" to "Approved"
+
+## Story Implementation (Developer)
+
+1. **Start new chat/conversation**
+2. **Load Dev agent**
+3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
+4. **Review generated report** in `{selected-story}`
+
+## Story Review (Quality Assurance)
+
+1. **Start new chat/conversation**
+2. **Load QA agent**
+3. **Execute**: `*review {selected-story}` (runs review-story task)
+4. **Review generated report** in `{selected-story}`
+
+## Commit Changes and Push
+
+1. **Commit changes**
+2. **Push to remote**
+
+## Repeat Until Complete
+
+- **SM**: Create next story → Review → Approve
+- **Dev**: Implement story → Complete → Mark Ready for Review
+- **QA**: Review story → Mark done
+- **Commit**: All changes
+- **Push**: To remote
+- **Continue**: Until all features implemented