# corradAF Framework - LLM Interaction Guide

## Metadata
- **Framework Name**: corradAF (Corrad Application Framework)
- **Framework Version**: 1.0.0
- **License**: MIT License
- **Base Technology**: Nuxt 3, Vue 3, TypeScript/JavaScript
- **UI Framework**: TailwindCSS with custom components
- **Database ORM**: Prisma
- **Supported Languages**: English (primary), multi-language ready
- **Input Format**: Text, Markdown, JSON for API specifications
- **Output Format**: Vue SFC components, TypeScript/JavaScript, JSON configurations

## Framework Overview

### Introduction:
corradAF is a comprehensive Nuxt.js template designed for rapid application development. It provides a complete development tools suite, authentication system, and modern UI components. This document defines interaction patterns for LLMs working with the corradAF framework.

### Core Architecture:
- **Frontend**: Nuxt 3 with Vue 3 Composition API
- **Styling**: TailwindCSS with custom component library
- **State Management**: Pinia stores
- **Authentication**: JWT-based with middleware protection
- **Database**: Prisma ORM with PostgreSQL (configurable)
- **Development Tools**: Built-in suite for rapid development

## Content Structure Guidelines

### File Organization:
```
├── pages/           # Route pages (Nuxt auto-routing)
├── components/      # Reusable Vue components
├── composables/     # Vue composables for shared logic
├── layouts/         # Application layouts
├── middleware/      # Route middleware (auth, permissions)
├── server/api/      # Server-side API endpoints
├── stores/          # Pinia state management
├── assets/          # Static assets and styles
├── public/          # Public static files
├── prisma/          # Database schema and migrations
└── devtool/         # Development tools pages
```

### Component Naming Conventions:
- **Pages**: Use kebab-case for file names (e.g., `user-management.vue`)
- **Components**: Use PascalCase for component names (e.g., `UserCard.vue`)
- **Composables**: Prefix with `use` (e.g., `useUserManagement.js`)
- **Stores**: Use camelCase with descriptive names (e.g., `userStore.js`)

## Writing Guidelines for LLMs

### Controlled Vocabulary:
- Use `navigateTo()` instead of `router.push()` for navigation (Nuxt 3 pattern)
- Use `definePageMeta()` for page configuration
- Use `ref()` and `reactive()` for Vue 3 Composition API
- Use `composables` instead of `mixins` for shared logic
- Use `middleware` for route protection and validation

### Grammar Rules:
- **Sentence Length**: Maximum 20 words for code comments
- **Active Voice**: Prefer active voice in documentation
- **Function Names**: Use camelCase with descriptive verbs
- **Variable Names**: Use camelCase with clear, descriptive nouns

### Code Style Guidelines:
- **Vue SFC Structure**: `<script setup>`, `<template>`, `<style>` order
- **Import Order**: Vue imports, Nuxt imports, local imports, type imports
- **Function Declaration**: Use `function` keyword for named functions, arrow functions for callbacks
- **Async/Await**: Prefer async/await over promises for better readability

## Component Templates

### Standard Vue SFC Component Template:
```vue
<script setup>
// Imports
import { ref, computed, onMounted } from 'vue'

// Props and emits
const props = defineProps({
  modelValue: {
    type: [String, Number, Boolean],
    default: null
  }
})

const emit = defineEmits(['update:modelValue', 'change'])

// Reactive data
const isLoading = ref(false)
const data = ref([])

// Computed properties
const processedData = computed(() => {
  return data.value.filter(item => item.active)
})

// Methods
function handleUpdate(value) {
  emit('update:modelValue', value)
  emit('change', value)
}

// Lifecycle
onMounted(async () => {
  await loadData()
})

async function loadData() {
  isLoading.value = true
  try {
    // Load data logic
  } catch (error) {
    console.error('Error loading data:', error)
  } finally {
    isLoading.value = false
  }
}
</script>

<template>
  <div class="component-wrapper">
    <!-- Component content -->
  </div>
</template>

<style scoped>
/* Component-specific styles */
</style>
```

### Page Component Template:
```vue
<script setup>
definePageMeta({
  title: "Page Title",
  middleware: ["auth"], // Add middleware as needed
  requiresAuth: true,
  breadcrumb: [
    {
      name: "Dashboard",
      path: "/dashboard",
    },
    {
      name: "Current Page",
      path: "/current-page",
    },
  ],
})

// Page-specific logic
</script>

<template>
  <div class="page-container">
    <LayoutsBreadcrumb />
    
    <!-- Page content -->
  </div>
</template>
```

### Development Tool Page Template:
```vue
<script setup>
definePageMeta({
  title: "Tool Name",
  middleware: ["auth", "dev-tools"],
  requiresAuth: true,
  layout: "devtool",
  breadcrumb: [
    {
      name: "Dashboard",
      path: "/dashboard",
    },
    {
      name: "Development Tools",
      path: "/devtool",
    },
    {
      name: "Tool Name",
      path: "/devtool/tool-name",
    },
  ],
})

// Tool-specific functionality
const toolData = ref([])
const isLoading = ref(false)

// CRUD operations
async function createItem(data) {
  // Implementation
}

async function updateItem(id, data) {
  // Implementation
}

async function deleteItem(id) {
  // Implementation
}
</script>

<template>
  <div class="devtool-container space-y-6">
    <div class="flex justify-between items-center">
      <h1 class="text-2xl font-bold text-primary">Tool Name</h1>
      <rs-button variant="primary" @click="createNew">
        <Icon name="mdi:plus" size="18" />
        Add New
      </rs-button>
    </div>
    
    <!-- Tool interface -->
  </div>
</template>
```

## API Endpoint Templates

### Server API Route Template:
```typescript
export default defineEventHandler(async (event) => {
  // Validate authentication
  const user = await requireUserSession(event)
  
  // Handle different HTTP methods
  const method = getMethod(event)
  
  if (method === 'GET') {
    // GET logic
    return { data: [] }
  }
  
  if (method === 'POST') {
    // POST logic
    const body = await readBody(event)
    
    // Validate input
    if (!body.name) {
      throw createError({
        statusCode: 400,
        statusMessage: 'Name is required'
      })
    }
    
    // Process request
    return { success: true, data: body }
  }
  
  // Handle other methods
  throw createError({
    statusCode: 405,
    statusMessage: 'Method not allowed'
  })
})
```

### API Response Format:
```json
{
  "success": true,
  "data": {},
  "message": "Operation completed successfully",
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}
```

### Error Response Format:
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": {}
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}
```

## Database Schema Patterns

### Prisma Model Template:
```prisma
model User {
  id          String   @id @default(cuid())
  email       String   @unique
  name        String?
  role        Role     @default(USER)
  isActive    Boolean  @default(true)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  // Relations
  profile     UserProfile?
  posts       Post[]
  
  @@map("users")
}

model UserProfile {
  id        String @id @default(cuid())
  userId    String @unique
  avatar    String?
  bio       String?
  
  user      User   @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@map("user_profiles")
}

enum Role {
  USER
  ADMIN
  DEVELOPER
}
```

## TailwindCSS and Styling Guidelines

### Component Styling Patterns:
- **Cards**: Use `rs-card` component or `bg-white rounded-lg shadow-sm border`
- **Buttons**: Use `rs-button` component with variants (primary, secondary, danger)
- **Forms**: Use FormKit components with TailwindCSS utilities
- **Grid Layouts**: Use `grid grid-cols-{n} gap-{size}` for responsive layouts
- **Spacing**: Use consistent spacing scale (4, 6, 8, 12, 16, 24)

### Color Scheme:
- **Primary**: `text-primary`, `bg-primary`
- **Secondary**: `text-secondary`, `bg-secondary`
- **Success**: `text-green-600`, `bg-green-100`
- **Warning**: `text-yellow-600`, `bg-yellow-100`
- **Danger**: `text-red-600`, `bg-red-100`

## Authentication and Security Patterns

### Route Protection:
```javascript
// middleware/auth.js
export default defineNuxtRouteMiddleware((to, from) => {
  const { $auth } = useNuxtApp()
  
  if (!$auth.user) {
    return navigateTo('/login')
  }
})

// middleware/dev-tools.js
export default defineNuxtRouteMiddleware((to, from) => {
  const { $auth } = useNuxtApp()
  
  if (!$auth.user?.isDeveloper) {
    throw createError({
      statusCode: 403,
      statusMessage: 'Access forbidden'
    })
  }
})
```

### API Security:
```typescript
// server/utils/auth.ts
export async function requireUserSession(event) {
  const token = getCookie(event, 'auth-token') || getHeader(event, 'authorization')
  
  if (!token) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Authentication required'
    })
  }
  
  try {
    const user = await verifyJWT(token)
    return user
  } catch (error) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Invalid token'
    })
  }
}
```

## Development Tools Integration

### Adding New Development Tools:
1. Create page in `pages/devtool/tool-name/`
2. Add navigation entry in navigation configuration
3. Implement CRUD operations
4. Add proper middleware and permissions
5. Follow established UI patterns

### Tool Configuration Template:
```javascript
// devtool configuration
export const toolConfig = {
  name: 'Tool Name',
  description: 'Tool description',
  icon: 'mdi:tool-icon',
  path: '/devtool/tool-name',
  permissions: ['developer', 'admin'],
  features: [
    'create',
    'read',
    'update',
    'delete',
    'export',
    'import'
  ]
}
```

## Input/Output Specifications for Code Generation

### Request Format for Component Generation:
```json
{
  "task": "component_generation",
  "type": "vue_component",
  "specifications": {
    "name": "UserCard",
    "props": ["user", "showActions"],
    "events": ["edit", "delete"],
    "features": ["responsive", "accessible"],
    "styling": "tailwindcss"
  }
}
```

### Response Format:
```json
{
  "success": true,
  "generated_code": "<!-- Vue component code -->",
  "file_path": "components/UserCard.vue",
  "dependencies": ["vue", "@nuxt/icon"],
  "usage_example": "<UserCard :user=\"user\" @edit=\"handleEdit\" />",
  "explanation": "Generated a responsive user card component with edit and delete actions."
}
```

## Error Handling Patterns

### Frontend Error Handling:
```javascript
// composables/useErrorHandler.js
export const useErrorHandler = () => {
  const handleError = (error, context = '') => {
    console.error(`Error in ${context}:`, error)
    
    // Show user-friendly message
    const { $toast } = useNuxtApp()
    $toast.error('An error occurred. Please try again.')
    
    // Log to monitoring service if available
    if (process.env.NODE_ENV === 'production') {
      // Log to external service
    }
  }
  
  return { handleError }
}
```

### API Error Handling:
```typescript
// server/utils/errorHandler.ts
export function handleAPIError(error: unknown) {
  if (error instanceof ValidationError) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Validation failed',
      data: error.details
    })
  }
  
  if (error instanceof DatabaseError) {
    throw createError({
      statusCode: 500,
      statusMessage: 'Database operation failed'
    })
  }
  
  // Generic error
  throw createError({
    statusCode: 500,
    statusMessage: 'Internal server error'
  })
}
```

## Testing Patterns

### Component Testing Template:
```javascript
// tests/components/UserCard.test.js
import { mount } from '@vue/test-utils'
import UserCard from '~/components/UserCard.vue'

describe('UserCard', () => {
  const mockUser = {
    id: '1',
    name: 'John Doe',
    email: 'john@example.com'
  }
  
  it('renders user information correctly', () => {
    const wrapper = mount(UserCard, {
      props: { user: mockUser }
    })
    
    expect(wrapper.text()).toContain('John Doe')
    expect(wrapper.text()).toContain('john@example.com')
  })
  
  it('emits edit event when edit button is clicked', async () => {
    const wrapper = mount(UserCard, {
      props: { user: mockUser, showActions: true }
    })
    
    await wrapper.find('[data-test="edit-button"]').trigger('click')
    
    expect(wrapper.emitted('edit')).toBeTruthy()
    expect(wrapper.emitted('edit')[0]).toEqual([mockUser])
  })
})
```

## Ethical Guidelines and Security Considerations

### Security Best Practices:
- **Input Validation**: Always validate and sanitize user inputs
- **SQL Injection Prevention**: Use Prisma ORM parameterized queries
- **XSS Prevention**: Use Vue's built-in template sanitization
- **CSRF Protection**: Implement CSRF tokens for state-changing operations
- **Authentication**: Use secure JWT implementation with proper expiration
- **Authorization**: Implement role-based access control (RBAC)

### Ethical Considerations:
- **Accessibility**: Follow WCAG 2.1 guidelines for component generation
- **Privacy**: Implement data protection and GDPR compliance patterns
- **Bias Prevention**: Ensure generated content is inclusive and unbiased
- **Performance**: Generate efficient code that doesn't compromise user experience

### Data Handling:
- **Encryption**: Use encryption for sensitive data storage
- **Logging**: Log security events without exposing sensitive information
- **Audit Trail**: Maintain audit logs for critical operations
- **Data Retention**: Implement proper data retention and deletion policies

## Performance Guidelines

### Code Generation Best Practices:
- **Lazy Loading**: Use dynamic imports for large components
- **Tree Shaking**: Write code that supports tree shaking
- **Bundle Size**: Consider bundle size impact in generated code
- **Caching**: Implement appropriate caching strategies
- **Database Queries**: Use efficient Prisma queries with proper relations

### Optimization Patterns:
```javascript
// Lazy component loading
const LazyComponent = defineAsyncComponent(() => import('~/components/HeavyComponent.vue'))

// Efficient data fetching
const { data, pending, error } = await useLazyFetch('/api/data', {
  key: 'unique-key',
  server: false // Client-side only if needed
})

// Computed optimization
const expensiveComputation = computed(() => {
  return useMemo(() => heavyOperation(props.data), [props.data])
})
```

---

This document serves as a comprehensive guide for LLMs working with the corradAF framework. It ensures consistent code generation, proper architecture patterns, and adherence to best practices for security, performance, and maintainability.