monacousa-portal/.clinerules/CLINE_WORKSPACE_RULES.md

# MonacoUSA Portal - Cline Workspace Rules

## Project Overview

This is the **MonacoUSA Portal** - a modern, responsive web portal built with Nuxt 3, Vuetify 3, and Keycloak authentication. The portal provides a unified dashboard for tools and services with mobile-first design and PWA capabilities.

## Tech Stack & Architecture

### Core Technologies
- **Framework**: Nuxt 3 with Vue 3 (SPA mode)
- **UI Library**: Vuetify 3 with MonacoUSA theme (#a31515 primary color)
- **Authentication**: Keycloak (OAuth2/OIDC)
- **Database**: NocoDB (API-first database)
- **File Storage**: MinIO (S3-compatible object storage)
- **PWA**: Vite PWA plugin with offline support
- **TypeScript**: Full TypeScript support throughout

### Project Structure
```
monacousa-portal/
├── components/          # Vue components
├── composables/         # Vue composables (useAuth, etc.)
├── layouts/            # Nuxt layouts (dashboard layout)
├── middleware/         # Route middleware (auth middleware)
├── pages/              # Application pages
│   ├── auth/           # Authentication pages
│   └── dashboard/      # Dashboard pages
├── plugins/            # Nuxt plugins
├── public/             # Static assets
├── server/             # Server-side code
│   ├── api/            # API routes
│   ├── utils/          # Server utilities
│   └── plugins/        # Server plugins
├── utils/              # Shared utilities
└── docs/               # Documentation
```

## Development Guidelines

### 1. Authentication System
- Uses Keycloak OAuth2/OIDC flow
- Session management with encrypted cookies
- `useAuth()` composable for authentication state
- Middleware protection for authenticated routes
- Support for user groups/roles (admin, manager, etc.)

### 2. API Structure
- RESTful APIs in `server/api/`
- Database operations via NocoDB client
- File operations via MinIO client
- Consistent error handling and responses
- Health check endpoint at `/api/health`

### 3. UI/UX Standards
- Mobile-first responsive design
- Vuetify 3 components with MonacoUSA theme
- Dashboard layout with collapsible sidebar
- PWA support with install prompts
- Consistent color scheme: #a31515 (primary), #ffffff (secondary)

### 4. File Organization
- Components in `components/` directory
- Composables for reusable logic
- Server utilities in `server/utils/`
- TypeScript types in `utils/types.ts`
- Environment configuration in `.env` files

## Coding Standards

### 1. Vue/Nuxt Patterns
```typescript
// Use composition API with <script setup>
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard',
  middleware: 'auth'
});

const { user, isAdmin } = useAuth();
</script>
```

### 2. API Route Patterns
```typescript
// server/api/example.ts
export default defineEventHandler(async (event) => {
  try {
    // Implementation
    return { success: true, data: result };
  } catch (error) {
    throw createError({
      statusCode: 500,
      statusMessage: 'Operation failed'
    });
  }
});
```

### 3. Database Operations
```typescript
// Use NocoDB client
const nocodb = createNocoDBClient();
const records = await nocodb.findAll('tableName', { limit: 10 });
```

### 4. File Storage
```typescript
// Use MinIO client
const minio = createMinIOClient();
await minio.uploadFile(fileName, buffer, contentType);
```

## Environment Configuration

### Required Environment Variables
```env
# Keycloak Configuration
NUXT_KEYCLOAK_ISSUER=https://auth.monacousa.org/realms/monacousa-portal
NUXT_KEYCLOAK_CLIENT_ID=monacousa-portal
NUXT_KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
NUXT_KEYCLOAK_CALLBACK_URL=https://monacousa.org/auth/callback

# NocoDB Configuration
NUXT_NOCODB_URL=https://db.monacousa.org
NUXT_NOCODB_TOKEN=your-nocodb-token
NUXT_NOCODB_BASE_ID=your-nocodb-base-id

# MinIO Configuration
NUXT_MINIO_ENDPOINT=s3.monacousa.org
NUXT_MINIO_PORT=443
NUXT_MINIO_USE_SSL=true
NUXT_MINIO_ACCESS_KEY=your-minio-access-key
NUXT_MINIO_SECRET_KEY=your-minio-secret-key
NUXT_MINIO_BUCKET_NAME=monacousa-portal

# Security Configuration
NUXT_SESSION_SECRET=your-48-character-session-secret-key-here
NUXT_ENCRYPTION_KEY=your-32-character-encryption-key-here

# Public Configuration
NUXT_PUBLIC_DOMAIN=monacousa.org
```

## Key Features & Capabilities

### 1. Authentication Flow
- OAuth2/OIDC with Keycloak
- Secure session management
- Role-based access control
- Automatic token refresh
- Logout functionality

### 2. Dashboard System
- Responsive sidebar navigation
- Role-based menu items
- PWA install prompts
- Mobile-optimized layout
- User profile display

### 3. File Management
- Upload/download via MinIO
- File type validation
- Progress indicators
- Error handling
- Secure file access

### 4. Database Integration
- CRUD operations via NocoDB
- Dynamic table access
- Query parameters support
- Error handling
- Type safety

### 5. PWA Features
- Offline support
- Install prompts
- Service worker
- App manifest
- Mobile optimization

## Development Commands

```bash
# Development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type checking
npm run typecheck
```

## Testing & Health Checks

### Health Check Endpoint
- `GET /api/health` - System health status
- Checks database, storage, and auth connectivity
- Returns status: healthy/degraded/unhealthy

### Manual Testing
1. Authentication flow (login/logout)
2. Dashboard navigation
3. File upload/download
4. Database operations
5. Mobile responsiveness
6. PWA installation

## Security Considerations

### 1. Session Security
- Encrypted session cookies
- Secure cookie settings
- HTTPS required in production
- Session timeout handling

### 2. API Security
- Authentication middleware
- Input validation
- Error message sanitization
- CORS configuration

### 3. File Security
- File type validation
- Size limits
- Secure storage
- Access control

## Deployment Guidelines

### 1. Production Requirements
- Node.js 18+
- SSL certificate
- Reverse proxy (nginx)
- Environment variables configured

### 2. Build Process
```bash
npm ci --only=production
npm run build
npm run preview
```

### 3. Health Monitoring
- Monitor `/api/health` endpoint
- Check service dependencies
- Monitor error logs
- Performance metrics

## Extension Guidelines

### Adding New Tools
1. Create page in `pages/dashboard/`
2. Add navigation item to dashboard layout
3. Implement API routes if needed
4. Add database tables in NocoDB
5. Update TypeScript types
6. Test authentication and permissions

### Adding New APIs
1. Create route in `server/api/`
2. Implement proper error handling
3. Add authentication if required
4. Update TypeScript types
5. Test with health checks

### Adding New Components
1. Create in `components/` directory
2. Follow Vuetify patterns
3. Ensure mobile responsiveness
4. Add proper TypeScript types
5. Test across devices

## Troubleshooting

### Common Issues
1. **Authentication failures**: Check Keycloak configuration
2. **Database errors**: Verify NocoDB connection and tokens
3. **File upload issues**: Check MinIO configuration and permissions
4. **Build errors**: Verify all environment variables are set
5. **Mobile issues**: Test responsive design and PWA features

### Debug Tools
- Browser developer tools
- Network tab for API calls
- Console for JavaScript errors
- Health check endpoint
- Server logs

## Best Practices

### 1. Code Quality
- Use TypeScript throughout
- Follow Vue 3 composition API patterns
- Implement proper error handling
- Write descriptive commit messages
- Keep components focused and reusable

### 2. Performance
- Lazy load components where appropriate
- Optimize images and assets
- Use proper caching strategies
- Monitor bundle size
- Implement proper loading states

### 3. Security
- Validate all inputs
- Use HTTPS in production
- Keep dependencies updated
- Follow OWASP guidelines
- Regular security audits

### 4. Maintainability
- Document complex logic
- Use consistent naming conventions
- Keep functions small and focused
- Separate concerns properly
- Regular code reviews

## Support & Resources

### Documentation
- Implementation guide: `MONACOUSA_PORTAL_IMPLEMENTATION.md`
- Nuxt 3 documentation
- Vuetify 3 documentation
- Keycloak documentation
- NocoDB API documentation

### Key Files to Reference
- `nuxt.config.ts` - Main configuration
- `server/utils/keycloak.ts` - Authentication logic
- `composables/useAuth.ts` - Auth composable
- `layouts/dashboard.vue` - Main layout
- `utils/types.ts` - TypeScript definitions

This workspace is designed to be a solid foundation for building custom tools and features while maintaining consistency, security, and performance standards.