340 lines
8.6 KiB
Markdown
340 lines
8.6 KiB
Markdown
|
# 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.
|