first commit
This commit is contained in:
commit
69fd120772
|
|
@ -0,0 +1,339 @@
|
|||
# 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.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,125 @@
|
|||
# MonacoUSA Portal Foundation
|
||||
|
||||
This folder contains the complete foundation and implementation guide for creating the **MonacoUSA Portal** - a modern, responsive web portal built with the same proven tech stack as the Port Nimara client portal.
|
||||
|
||||
## 📁 Contents
|
||||
|
||||
### 1. `MONACOUSA_PORTAL_IMPLEMENTATION.md`
|
||||
**Complete step-by-step implementation guide** containing:
|
||||
- ✅ Full project setup instructions
|
||||
- ✅ All code templates and configurations
|
||||
- ✅ Keycloak authentication implementation
|
||||
- ✅ NocoDB database integration
|
||||
- ✅ MinIO file storage setup
|
||||
- ✅ Responsive dashboard with Vuetify 3
|
||||
- ✅ PWA configuration
|
||||
- ✅ Production deployment guide
|
||||
- ✅ Testing and verification steps
|
||||
|
||||
### 2. `CLINE_WORKSPACE_RULES.md`
|
||||
**Cline workspace configuration file** containing:
|
||||
- 🔧 Project overview and tech stack details
|
||||
- 🔧 Development guidelines and coding standards
|
||||
- 🔧 Environment configuration requirements
|
||||
- 🔧 Key features and capabilities
|
||||
- 🔧 Extension guidelines for adding new tools
|
||||
- 🔧 Troubleshooting and best practices
|
||||
- 🔧 Support resources and documentation
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Give the implementation guide to another Claude instance**:
|
||||
- Copy the contents of `MONACOUSA_PORTAL_IMPLEMENTATION.md`
|
||||
- Provide it to Claude with instructions to follow the guide step-by-step
|
||||
|
||||
2. **Set up Cline workspace rules**:
|
||||
- Copy the contents of `CLINE_WORKSPACE_RULES.md`
|
||||
- Add it to your Cline workspace rules for the new project
|
||||
|
||||
## 🎯 Project Specifications
|
||||
|
||||
- **Name**: monacousa-portal
|
||||
- **Domain**: monacousa.org (configurable)
|
||||
- **Colors**: #a31515 (MonacoUSA red) primary, #ffffff (white) secondary
|
||||
- **Tech Stack**: Nuxt 3, Vue 3, Vuetify 3, Keycloak, NocoDB, MinIO
|
||||
- **Features**: PWA, Mobile-responsive, Dashboard layout, File storage
|
||||
|
||||
## 📋 What You'll Get
|
||||
|
||||
Following this implementation guide will create a complete portal foundation with:
|
||||
|
||||
### ✅ Authentication System
|
||||
- Keycloak OAuth2/OIDC integration
|
||||
- Secure session management
|
||||
- Role-based access control
|
||||
- Login/logout functionality
|
||||
|
||||
### ✅ Responsive Dashboard
|
||||
- Mobile-first design
|
||||
- Collapsible sidebar navigation
|
||||
- User profile display
|
||||
- Role-based menu items
|
||||
|
||||
### ✅ File Management
|
||||
- MinIO S3-compatible storage
|
||||
- Upload/download functionality
|
||||
- File type validation
|
||||
- Secure access control
|
||||
|
||||
### ✅ Database Integration
|
||||
- NocoDB API-first database
|
||||
- CRUD operations
|
||||
- Dynamic table access
|
||||
- Type-safe operations
|
||||
|
||||
### ✅ PWA Features
|
||||
- Offline support
|
||||
- Install prompts
|
||||
- Service worker
|
||||
- Mobile optimization
|
||||
|
||||
### ✅ Production Ready
|
||||
- Health check endpoints
|
||||
- Error handling
|
||||
- Security best practices
|
||||
- Deployment configuration
|
||||
|
||||
## 🛠️ Usage Instructions
|
||||
|
||||
### For Implementation
|
||||
1. Create a new repository for your MonacoUSA Portal
|
||||
2. Follow the step-by-step guide in `MONACOUSA_PORTAL_IMPLEMENTATION.md`
|
||||
3. Configure your environment variables
|
||||
4. Set up Keycloak, NocoDB, and MinIO services
|
||||
5. Test the implementation
|
||||
6. Deploy to production
|
||||
|
||||
### For Development
|
||||
1. Use `CLINE_WORKSPACE_RULES.md` as your Cline workspace rules
|
||||
2. Follow the coding standards and guidelines
|
||||
3. Extend the portal with your custom tools
|
||||
4. Maintain consistency with the established patterns
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
The foundation is designed to be easily customizable:
|
||||
- **Branding**: Update colors, logos, and text
|
||||
- **Tools**: Add new dashboard pages and functionality
|
||||
- **APIs**: Extend with custom server endpoints
|
||||
- **Database**: Add new tables and data structures
|
||||
- **UI**: Customize components and layouts
|
||||
|
||||
## 📞 Support
|
||||
|
||||
This foundation is based on the proven Port Nimara client portal architecture and includes:
|
||||
- Comprehensive documentation
|
||||
- Complete code examples
|
||||
- Best practices and patterns
|
||||
- Troubleshooting guides
|
||||
- Extension guidelines
|
||||
|
||||
The implementation guide is self-contained and can be followed by any developer or AI assistant to create the exact foundation you need.
|
||||
|
||||
---
|
||||
|
||||
**Ready to build your MonacoUSA Portal!** 🚀
|
||||
Loading…
Reference in New Issue